IF Commons GitHub

contracts-time-control

0062Active

0062-contracts-time-control · owner if · domain data

Requirements

FR-001checkpassing

The model MUST be a module of governance named contract that requires nothing, with a data contract as a record of the dataset, version (unique with the dataset), status, owner and the instants between which it holds, and each field it promises as a record of its name, datatype, whether it may be missing and its classification, of one contract.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the contract model has contracts with their fields, periods, controls with their runs (only added to), consents and canary tokens; the contracts, periods and consents are annotated effective-dated with members that exist; every concept is defined

Proved by: data/suite/contract.test.ts

Written in: data/models/contract/mod.ts

Tests: passed: suite/contract.test.ts the contract model has contracts with their fields, periods, controls with their runs (onl

FR-002checkpassing

A period MUST be a record of a scope, the instants it starts at and ends before, its status, who closed it and when, and the reason it was opened again.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the contract model has contracts with their fields, periods, controls with their runs (only added to), consents and canary tokens; the contracts, periods and consents are annotated effective-dated with members that exist; every concept is defined

Proved by: data/suite/contract.test.ts

Written in: data/models/contract/mod.ts

Tests: passed: suite/contract.test.ts the contract model has contracts with their fields, periods, controls with their runs (onl

FR-003checkpassing

A control MUST be a record of what must hold, who answers for it, how often it is checked in days, the evidence that checks it and the framework it answers to, and a run of a control MUST be a record of the control, what it found, when and the evidence, annotated append-only.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the contract model has contracts with their fields, periods, controls with their runs (only added to), consents and canary tokens; the contracts, periods and consents are annotated effective-dated with members that exist; every concept is defined

Proved by: data/suite/contract.test.ts

Written in: data/models/contract/mod.ts

Tests: passed: suite/contract.test.ts the contract model has contracts with their fields, periods, controls with their runs (onl

FR-004checkpassing

A consent MUST be a record of a pseudonymous subject, a purpose, whether it is granted or withdrawn and the instants between which it holds.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the contract model has contracts with their fields, periods, controls with their runs (only added to), consents and canary tokens; the contracts, periods and consents are annotated effective-dated with members that exist; every concept is defined

Proved by: data/suite/contract.test.ts

Written in: data/models/contract/mod.ts

Tests: passed: suite/contract.test.ts the contract model has contracts with their fields, periods, controls with their runs (onl

FR-005checkpassing

A canary token MUST be a record of the made-up value, where it was planted, when and what its appearance would mean.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the contract model has contracts with their fields, periods, controls with their runs (only added to), consents and canary tokens; the contracts, periods and consents are annotated effective-dated with members that exist; every concept is defined

Proved by: data/suite/contract.test.ts

Written in: data/models/contract/mod.ts

Tests: passed: suite/contract.test.ts the contract model has contracts with their fields, periods, controls with their runs (onl

FR-006checkpassing

The status of a contract, of a period, the result of a control run and the status of a consent MUST be closed code lists, and every concept MUST be defined.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the contract model has contracts with their fields, periods, controls with their runs (only added to), consents and canary tokens; the contracts, periods and consents are annotated effective-dated with members that exist; every concept is defined

Proved by: data/suite/contract.test.ts

Written in: data/models/contract/mod.ts

Tests: passed: suite/contract.test.ts the contract model has contracts with their fields, periods, controls with their runs (onl

FR-007checkpassing

The quality vocabulary MUST have temporal (a concept, the member that says from when a record holds and the one that says until when), the contracts, the periods and the consents MUST carry it, and lint MUST find a member it names that the concept does not have.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the contract model has contracts with their fields, periods, controls with their runs (only added to), consents and canary tokens; the contracts, periods and consents are annotated effective-dated with members that exist; every concept is defined

Proved by: data/suite/contract.test.ts

Written in: data/models/contract/mod.ts

Tests: passed: suite/contract.test.ts the contract model has contracts with their fields, periods, controls with their runs (onl

FR-008checkpassing

compatibility MUST compare the fields of two versions of a contract with a matrix that says for each kind of change (a field added optional or required, removed, retyped, made nullable or required, a label raised or lowered) whether a reader and a writer of the old version still work, and say whether readers or writers break; fieldsOf MUST read the fields of a version.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the compatibility matrix tells a breaking change to readers from one to writers: a removed field, a retyped one, one that became nullable or a label raised break readers; a required field added breaks writers; an optional field added breaks nobody

Proved by: data/suite/contract.test.ts

Written in: data/sql/contract/mod.ts

Tests: passed: suite/contract.test.ts the compatibility matrix tells a breaking change to readers from one to writers: a removed

FR-009checkpassing

holdsAt MUST be the predicate that says a record holds at an instant (it began at or before and has no end or ends after, the end not being included) in a typed query on every engine, for instants written as the same text form.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: holdsAt reads a record as of an instant on every engine: it began at or before it and has no end or ends after it, and the end is not included

Proved by: data/suite/contract.test.ts

Written in: data/sql/contract/mod.ts

Tests: passed: suite/contract.test.ts holdsAt reads a record as of an instant on every engine: it began at or before it and has

FR-010checkpassing

closePeriod MUST close a period and keep who and when; reopenPeriod MUST refuse without a reason; and place MUST put a change 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 its date.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: a closed period takes no change: a change dated in it is placed as an adjustment of the next open period, one in an open period stays in it, one in no period is placed nowhere, and reopening needs a reason

Proved by: data/suite/contract.test.ts

Written in: data/sql/contract/mod.ts

Tests: passed: suite/contract.test.ts a closed period takes no change: a change dated in it is placed as an adjustment of the ne

FR-011checkpassing

recordRun MUST add a run of a control, and matrix MUST give for each control, from its latest run at the time asked, passing, failing (a failure or a run that was due and not made), waived, overdue where a pass is older than the frequency, or never run.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the control matrix computes passing, failing, waived, overdue and never-run from the latest run and the frequency of each control

Proved by: data/suite/contract.test.ts

Written in: data/sql/contract/mod.ts

Tests: passed: suite/contract.test.ts the control matrix computes passing, failing, waived, overdue and never-run from the lates

FR-012checkpassing

permits MUST say whether a consent that is granted holds for a subject and purpose at an instant, and unconsented MUST return the uses that no consent covers, so that a policy is a test that fails with them.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: consent is a test: a use with a consent in force for its purpose passes, and one outside its dates, for another purpose, withdrawn or with none is returned

Proved by: data/suite/contract.test.ts

Written in: data/sql/contract/mod.ts

Tests: passed: suite/contract.test.ts consent is a test: a use with a consent in force for its purpose passes, and one outside i

FR-013checkpassing

plant MUST record a canary token and scanCanaries MUST return where a planted token is found in text, other than the place it was planted in.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: a planted canary token is found in text outside the place that holds it and not in that place

Proved by: data/suite/contract.test.ts

Written in: data/sql/contract/mod.ts

Tests: passed: suite/contract.test.ts a planted canary token is found in text outside the place that holds it and not in that pl

FR-014checkpassing

propagate MUST give the highest of a set of labels, and labelViolations MUST find each dataset that is labelled lower than the highest of the datasets it is made from at any distance on the lineage, and name what makes it so.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: a label is the highest of what a dataset is made from, however far back, and a derived dataset labelled lower is a violation that names what makes it so

Proved by: data/suite/contract.test.ts

Written in: data/sql/contract/mod.ts

Tests: passed: suite/contract.test.ts a label is the highest of what a dataset is made from, however far back, and a derived dat

FR-015checkpassing

layerReport MUST say by table, in words, where the physical layer disagrees with the logical one (from drift), and give nothing where they agree.

Enforced (check): .github: cd commons/data && bun run verify — suite/contract.test.ts: the layer report says by table where the physical layer disagrees with the logical, in words, and says nothing where they agree

Proved by: data/suite/contract.test.ts

Written in: data/sql/contract/mod.ts

Tests: passed: suite/contract.test.ts the layer report says by table where the physical layer disagrees with the logical, in wor

Out of scope

  • Enforcing a contract on an incoming file, or on a stream: a later stage uses the contract; the codecs of commons/integrations read the messages.
  • Generating a contract from a table, or a table from a contract: the layers already do the second, and the first is adopt.
  • Reports for an auditor in the format of a framework: commons/grc's.

Edge cases

  • Instants are compared as the text they are written in; write them with toISOString(), per FR-009.
  • A period whose next ones are all closed has no place for an adjustment, per FR-010.
  • A control that was due and recorded not_run is failing, per FR-011.

Assumptions

  • The tables are made by bind from the model on any of SQLite, DuckDB and PostgreSQL; the fixtures of the tests are synthetic.

Open questions

OQ-1open question

Whether the compatibility matrix should be data (a table) so that a project can tighten it, or stay a constant of the library.

Key entities

  • Data contract - what a dataset promises, in one version.
  • Period - a span of time that takes changes until it is closed.
  • Control - what must hold, with the history of its runs.
  • Consent - a subject's permission for a purpose between two dates.

Success criteria

SC-001success criterion

Whether two versions of a contract break a reader, which period a late change belongs to, which controls are failing or overdue and which uses had no consent are each one call, and a derived dataset cannot be labelled lower than its sources without a finding.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Data, models/contract/mod, sql/contract/mod

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