FieldSpecinterfaceno test imports itinterface FieldSpecA field of a contract, as the comparison sees it.
| Member | Type | What it is |
|---|---|---|
name | string | |
datatype | string | |
nullable | boolean | |
classification? | string |
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.
FieldSpecinterfaceno test imports itinterface FieldSpecA field of a contract, as the comparison sees it.
| Member | Type | What it is |
|---|---|---|
name | string | |
datatype | string | |
nullable | boolean | |
classification? | string |
LABELSconstno test imports itconst LABELS: readonly ["public", "internal", "confidential", "restricted"]The labels of sensitivity, the lowest first.
Labeltypeno test imports ittype Label = (typeof LABELS)[number];A label of sensitivity.
Effectinterfaceno test imports itinterface EffectWhat a change of a contract does to those who read the data and to those who write it.
| Member | Type | What it is |
|---|---|---|
readers | "breaking" | "compatible" | |
writers | "breaking" | "compatible" |
MATRIXconstno test imports itconst 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 itinterface FieldChangeOne change between two versions of a contract.
| Member | Type | What it is |
|---|---|---|
field | string | |
kind | "became-nullable" | "became-required" | "field-added-optional" | "field-added-required" | "field-removed" | "label-lowered" | "label-raised" | "type-changed" | |
effect | Effect |
Compatibilityinterfaceno test imports itinterface CompatibilityWhat comparing two versions found.
| Member | Type | What it is |
|---|---|---|
changes | readonly FieldChange[] | |
readersBreak | boolean | |
writersBreak | boolean |
compatibilityfunctionfunction compatibility(before: readonly FieldSpec[], after: readonly FieldSpec[]): CompatibilityCompares the fields of two versions of a contract with the matrix.
fieldsOffunctionfunction fieldsOf(on: Runner, dataset: string, version: string): Promise<readonly FieldSpec[]>Reads the fields of one version of a contract.
holdsAtfunctionfunction 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.
Placementtypeno test imports ittype 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.
closePeriodfunctionfunction 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.
reopenPeriodfunctionfunction reopenPeriod(on: Runner, periodId: string, reason: string): Promise<void>Opens a closed period again, with the reason, which is not optional.
placefunctionfunction 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.
recordRunfunctionfunction 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.
ControlStatusinterfaceno test imports itinterface ControlStatusWhat the matrix says of one control now.
| Member | Type | What it is |
|---|---|---|
controlId | string | |
owner | string | |
framework | string | null | |
status | "failing" | "never-run" | "overdue" | "passing" | "waived" | |
lastRun | string | null |
matrixfunctionfunction 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.
permitsfunctionfunction 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.
unconsentedfunctionfunction unconsented(on: Runner, uses: Iterable<Use>): Promise<readonly Use[]>The uses that no consent covers: the failures of a policy that is a test.
CanaryHitinterfaceno test imports itinterface CanaryHitA canary where it should not be.
| Member | Type | What it is |
|---|---|---|
token | string | |
where | string | |
plantedIn | string |
plantfunctionfunction plant(on: Runner, token: string, plantedIn: string, purpose: string, at?: string | Date): Promise<void>Plants a token.
scanCanariesfunctionfunction 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.
propagatefunctionfunction propagate(labels: readonly string[]): "confidential" | "internal" | "public" | "restricted"The label of what is made from sources: the highest of theirs.
LabelViolationinterfaceno test imports itinterface LabelViolationA derived dataset that is labelled lower than what it is made from.
| Member | Type | What it is |
|---|---|---|
dataset | string | |
declared | string | |
required | "confidential" | "internal" | "public" | "restricted" | |
because | readonly string[] |
labelViolationsfunctionfunction 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.
LayerDisagreementinterfaceno test imports itinterface LayerDisagreementThe differences between the layers of one table.
| Member | Type | What it is |
|---|---|---|
table | string | |
between | "logical and physical" | |
lines | readonly string[] |
layerReportfunctionfunction 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.