IF Commons GitHub

operating-model

0063Active

0063-operating-model · owner if · domain data

Requirements

FR-001checkpassing

The model MUST be a module of governance named operations that requires nothing, with a waiting-on ledger as records of what is waited on, from whom, since when, by when, its status and when it came, with the status a closed code list (open, resolved, cancelled).

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: the operations model has the waiting-on ledger, decision records that can replace one another, limits, the copy inventory, environments with releases and a promotion log that is only added to, workloads with their recorded statements, the signal catalog and the freshness rules, with closed code lists and every concept defined

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts the operations model has the waiting-on ledger, decision records that can replace one anot

FR-002checkpassing

A decision MUST be a record of its title, context, outcome, consequences, status (proposed, accepted, rejected, superseded as a closed code list), who decided and when, and the decision it replaced.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: the operations model has the waiting-on ledger, decision records that can replace one another, limits, the copy inventory, environments with releases and a promotion log that is only added to, workloads with their recorded statements, the signal catalog and the freshness rules, with closed code lists and every concept defined

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts the operations model has the waiting-on ledger, decision records that can replace one anot

FR-003checkpassing

A limit MUST be a record of what runs out, its kind (a closed code list: certificate, credential, quota, license, agreement), when, who renews it and how many days before it someone must act.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: the operations model has the waiting-on ledger, decision records that can replace one another, limits, the copy inventory, environments with releases and a promotion log that is only added to, workloads with their recorded statements, the signal catalog and the freshness rules, with closed code lists and every concept defined

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts the operations model has the waiting-on ledger, decision records that can replace one anot

FR-004checkpassing

A copy of data MUST be a record of the dataset, the place, why it exists, who answers for it, its classification and when it was last refreshed.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: the operations model has the waiting-on ledger, decision records that can replace one another, limits, the copy inventory, environments with releases and a promotion log that is only added to, workloads with their recorded statements, the signal catalog and the freshness rules, with closed code lists and every concept defined

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts the operations model has the waiting-on ledger, decision records that can replace one anot

FR-005checkpassing

An environment MUST be a record of its name (unique), its kind (a closed code list in the order of promotion: development, test, staging, production), whether it holds real data and its owner, and a release a record of the artifact and version (unique), when it was cut and its evidence, and the promotion log MUST be records of a release arriving in an environment, who, when and the evidence, annotated append-only.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: the operations model has the waiting-on ledger, decision records that can replace one another, limits, the copy inventory, environments with releases and a promotion log that is only added to, workloads with their recorded statements, the signal catalog and the freshness rules, with closed code lists and every concept defined

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts the operations model has the waiting-on ledger, decision records that can replace one anot

FR-006checkpassing

A workload MUST be a record of its name (unique), owner, schedule and criticality, and a statement of it a record of a single select with the rows and the SHA-256 of the rows it gave when recorded.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: the operations model has the waiting-on ledger, decision records that can replace one another, limits, the copy inventory, environments with releases and a promotion log that is only added to, workloads with their recorded statements, the signal catalog and the freshness rules, with closed code lists and every concept defined

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts the operations model has the waiting-on ledger, decision records that can replace one anot

FR-007checkpassing

A signal MUST be a record of its name, its kind (a closed code list: counter, gauge, histogram, event), unit, the attributes it carries, what it measures and who answers for it, and a freshness rule a record of a source (unique), the hours its latest load may be old and who is told; every concept MUST be defined.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: the operations model has the waiting-on ledger, decision records that can replace one another, limits, the copy inventory, environments with releases and a promotion log that is only added to, workloads with their recorded statements, the signal catalog and the freshness rules, with closed code lists and every concept defined

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts the operations model has the waiting-on ledger, decision records that can replace one anot

FR-008checkpassing

waitingOn MUST list what is open, the oldest first, with the days it has been waited on and the status overdue where its date has passed and waiting where not; resolveWait MUST mark one as resolved with when.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: the waiting-on ledger lists what is open, the oldest first, as overdue once its date has passed, and drops what has come

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts the waiting-on ledger lists what is open, the oldest first, as overdue once its date has p

FR-009checkpassing

supersede MUST accept the new decision with the one it replaced and mark the replaced one superseded, and decisionsInForce MUST list the accepted decisions and no others.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: a decision that replaces another is accepted and says what it replaced, the replaced one is marked, and only accepted decisions are in force

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts a decision that replaces another is accepted and says what it replaced, the replaced one i

FR-010checkpassing

limitsDue MUST list the limits that are expired or within the days of notice their owner needs, the soonest first, with the days left, and not a limit that is further off or has no end.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: limits are found when the time to act has come: expired ones and ones within the days of notice their owner needs, the soonest first, and not those further off

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts limits are found when the time to act has come: expired ones and ones within the days of n

FR-011checkpassing

copyFindings MUST list the copies with no owner, never refreshed, or not refreshed within the days given, each with the reason.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: copies of data with no owner, never refreshed or not refreshed within the days given are found, and a copy that is owned and fresh is not

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts copies of data with no owner, never refreshed or not refreshed within the days given are f

FR-012checkpassing

promote MUST add to the log a release's arrival in an environment only where the environment before it in the order has had it, and refuse, writing nothing, where it has not, where the release or environment does not exist, or where it goes to production with no evidence of the release or the promotion.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: a release is promoted only in the order of the environments and to production only with evidence, a refused promotion writes nothing, parity says which environments are behind, and real data outside production is found

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts a release is promoted only in the order of the environments and to production only with ev

FR-013checkpassing

parity MUST give the version of an artifact that each environment last received and the environments that are not at the version of the furthest one, and realDataOutsideProduction MUST name the environments that hold real data and are not production.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: a release is promoted only in the order of the environments and to production only with evidence, a refused promotion writes nothing, parity says which environments are behind, and real data outside production is found

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts a release is promoted only in the order of the environments and to production only with ev

FR-014checkpassing

catalog MUST read the signals and sample MUST make a sample with its kind and unit and throw for a name not in the catalog, attributes that are not exactly the signal's, or a counter that goes down.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: a signal is made only as the catalog defines it: an unknown name, other attributes or a counter that goes down are refused, and a sample carries its kind and unit

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts a signal is made only as the catalog defines it: an unknown name, other attributes or a co

FR-015checkpassing

freshness MUST give for each rule fresh where the latest load of its source that was not undone is within the hours, stale past them and never-loaded where there is none, with its age.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: freshness is computed from the latest load of a source that was not undone: fresh within the hours, stale past them, never loaded where there is none

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts freshness is computed from the latest load of a source that was not undone: fresh within t

FR-016checkpassing

replayWorkload MUST run the recorded statements of a workload and say for each the rows it gave, the rows recorded and whether the rows are the same by their hash, and MUST refuse and not run a statement that is not a single select.

Enforced (check): .github: cd commons/data && bun run verify — suite/operating-model.test.ts: the recorded statements of a workload are replayed and compared with the rows and hash recorded: the same after no change, different after one, and anything but a single select is refused and not run

Proved by: data/suite/operating-model.test.ts

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

Tests: passed: suite/operating-model.test.ts the recorded statements of a workload are replayed and compared with the rows and hash rec

Out of scope

  • Streaming and the signals of a stream: a later stage; the catalog and the emitters are what it will use.
  • Sending a sample to a telemetry backend: commons/telemetry's; this library makes the sample and checks it, and imports nothing of it.
  • Running a release or a rollback: the lifecycle runs the changes, and 0064 proves the recovery.

Edge cases

  • A wait with no date is never overdue, per FR-008.
  • A release that is promoted to the same environment again is a new row of the log and the latest decides parity, per FR-013.
  • Parity compares to the furthest environment that has any version, not to production by name, per FR-013.

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 sample should also be given to the telemetry library as a typed emitter, once that library's own spec offers one.

Key entities

  • Waiting - what the work waits on, from whom, with a computed status.
  • Decision - what was decided and what it replaced.
  • Limit - what runs out and who renews it.
  • Promotion - a release arriving in an environment: the log.
  • Signal - a measurement every emitter agrees on.

Success criteria

SC-001success criterion

What the platform waits on, what will expire, which copies have no owner, what version runs where, which sources are stale and whether a workload still gives what it gave are each one call, with no step of a release skipped.

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/operations/mod, sql/operations/mod

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