IF Commons GitHub

sql/contract/mod

Written to: 8 requirements: 8 proved, 0 partly, 0 failing, 0 with no test recorded. 0062-contracts-time-control FR-008, 0062-contracts-time-control FR-009, 0062-contracts-time-control FR-010, 0062-contracts-time-control FR-011, 0062-contracts-time-control FR-012, 0062-contracts-time-control FR-013 and 2 more

Contracts, time and control at work (commons data 0062-contracts-time-control): the code that works on the tables of the contract model (models/contract) and the checks that need none. Two versions of a contract are compared by a matrix that says which change breaks a reader and which a writer; "as of" is asked of an effective-dated table with one predicate; a period is closed and reopened, and a change dated in a closed one is placed in the next open one; a control matrix computes from the runs whether each control is passing, failing, waived, overdue or never run; a consent is a test (which uses had none); canary tokens are found where they should not be; a label is propagated to what is derived from it and a derived table that is labelled lower than its sources is a violation; and the differences between the layers are reported by table.

Source: commons/data/sql/contract/mod.ts

15 of 27 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

FieldSpecinterfaceno test imports it
interface FieldSpec

A field of a contract, as the comparison sees it.

MemberTypeWhat it is
namestring
datatypestring
nullableboolean
classification?string
LABELSconstno test imports it
const LABELS: readonly ["public", "internal", "confidential", "restricted"]

The labels of sensitivity, the lowest first.

Labeltypeno test imports it
type Label = (typeof LABELS)[number];

A label of sensitivity.

Effectinterfaceno test imports it
interface Effect

What a change of a contract does to those who read the data and to those who write it.

MemberTypeWhat it is
readers"breaking" | "compatible"
writers"breaking" | "compatible"
MATRIXconstno test imports it
const MATRIX: { readonly "field-added-optional": { readonly readers: "compatible"; readonly writers: "compatible"; }; re… (779 characters)
const MATRIX: { readonly "field-added-optional": { readonly readers: "compatible"; readonly writers: "compatible"; }; readonly "field-added-required": { readonly readers: "compatible"; readonly writers: "breaking"; }; readonly "field-removed": { readonly readers: "breaking"; readonly writers: "compatible"; }; readonly "type-changed": { readonly readers: "breaking"; readonly writers: "breaking"; }; readonly "became-nullable": { readonly readers: "breaking"; readonly writers: "compatible"; }; readonly "became-required": { readonly readers: "compatible"; readonly writers: "breaking"; }; readonly "label-raised": { readonly readers: "breaking"; readonly writers: "compatible"; }; readonly "label-lowered": { readonly readers: "compatible"; readonly writers: "compatible"; }; }

The compatibility matrix: for each kind of change, whether a reader and a writer written for the old version still work. Dropping or retyping a field, or letting a field become missing, breaks readers; adding a field that must be given breaks writers; raising a label breaks readers who are not cleared for it.

FieldChangeinterfaceno test imports it
interface FieldChange

One change between two versions of a contract.

MemberTypeWhat it is
fieldstring
kind"became-nullable" | "became-required" | "field-added-optional" | "field-added-required" | "field-removed" | "label-lowered" | "label-raised" | "type-changed"
effectEffect
Compatibilityinterfaceno test imports it
interface Compatibility

What comparing two versions found.

MemberTypeWhat it is
changesreadonly FieldChange[]
readersBreakboolean
writersBreakboolean
compatibilityfunction
function compatibility(before: readonly FieldSpec[], after: readonly FieldSpec[]): Compatibility

Compares the fields of two versions of a contract with the matrix.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

fieldsOffunction
function fieldsOf(on: Runner, dataset: string, version: string): Promise<readonly FieldSpec[]>

Reads the fields of one version of a contract.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

holdsAtfunction
function holdsAt(validFrom: Expr<string | Date>, validTo: Expr<string | Date | null>, at: string | Date): Expr<boolean>

The predicate that says a record holds at an instant: it began at or before it, and has no end or ends after it.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

Placementtypeno test imports it
type Placement =
  | { readonly kind: "open"; readonly periodId: string }
  | { readonly kind: "adjustment"; readonly belongsTo: string; readonly periodId: string }
  | { readonly kind: "none" };

Where a change dated at an instant is placed.

closePeriodfunction
function closePeriod(on: Runner, periodId: string, by: string, at?: string | Date): Promise<void>

Closes a period: it takes no changes from now on, and who closed it and when are kept.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

reopenPeriodfunction
function reopenPeriod(on: Runner, periodId: string, reason: string): Promise<void>

Opens a closed period again, with the reason, which is not optional.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

placefunction
function place(on: Runner, scope: string, dated: string | Date): Promise<Placement>

Places a change dated at an instant: in its own period where that takes changes, as an adjustment of the next open period where its own is closed, and nowhere where no period holds it.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

recordRunfunction
function recordRun(on: Runner, run: { readonly controlRunId: string; readonly controlId: string; readonly result: "fail" | "not_run" | "pass" | "waived"; readonly ranAt: string | Date; readonly evidence?: string | undefined; }): Promise<void>

Adds a run of a control to its history.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

ControlStatusinterfaceno test imports it
interface ControlStatus

What the matrix says of one control now.

MemberTypeWhat it is
controlIdstring
ownerstring
frameworkstring | null
status"failing" | "never-run" | "overdue" | "passing" | "waived"
lastRunstring | null
matrixfunction
function matrix(on: Runner, asOf?: string | Date): Promise<readonly ControlStatus[]>

The control matrix: each control with the status that follows from its runs. The latest run decides: a failure is failing, a waiver is waived, a pass is passing unless it is older than the control's frequency (in days), which makes it overdue; a control that was never run says so.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

permitsfunction
function permits(on: Runner, subject: string, purpose: string, at: string | Date): Promise<boolean>

Whether a consent in force covers a purpose at an instant, and has not been withdrawn.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

unconsentedfunction
function unconsented(on: Runner, uses: Iterable<Use>): Promise<readonly Use[]>

The uses that no consent covers: the failures of a policy that is a test.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

CanaryHitinterfaceno test imports it
interface CanaryHit

A canary where it should not be.

MemberTypeWhat it is
tokenstring
wherestring
plantedInstring
plantfunction
function plant(on: Runner, token: string, plantedIn: string, purpose: string, at?: string | Date): Promise<void>

Plants a token.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

scanCanariesfunction
function scanCanaries(on: Runner, texts: Iterable<{ readonly where: string; readonly text: string; }>): Promise<readonly CanaryHit[]>

Looks in text for the planted tokens, where they are not the place that holds them, and says where each was found.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

propagatefunction
function propagate(labels: readonly string[]): "confidential" | "internal" | "public" | "restricted"

The label of what is made from sources: the highest of theirs.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

LabelViolationinterfaceno test imports it
interface LabelViolation

A derived dataset that is labelled lower than what it is made from.

MemberTypeWhat it is
datasetstring
declaredstring
required"confidential" | "internal" | "public" | "restricted"
becausereadonly string[]
labelViolationsfunction
function labelViolations(edges: readonly { readonly from: string; readonly to: string; }[], declared: Readonly<Record<string, string>>): readonly LabelViolation[]

Checks labels along the lineage: each dataset must be labelled at least as high as the highest of the datasets it is made from, however far back.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

LayerDisagreementinterfaceno test imports it
interface LayerDisagreement

The differences between the layers of one table.

MemberTypeWhat it is
tablestring
between"logical and physical"
linesreadonly string[]
layerReportfunction
function layerReport(found: readonly Drift[]): readonly LayerDisagreement[]

Says where the physical layer disagrees with the logical one, table by table, in words a person can act on.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.