IF Commons GitHub

The issues model and its synchronisation

0045Active

0045-issues-model · owner if · domain data

Requirements

FR-001checkpassing

The issues model MUST be a module that requires no other and composes alone, with closed code lists for severity, priority, size, status, presence, evidence kind, link kind, goal and outcome, and its tables MUST bind on every dialect.

Enforced (check): .github: cd commons/data && bun run verify — suite/issues-sync.test.ts: the issues model composes alone and binds on every dialect

Proved by: data/suite/issues-sync.test.ts

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

Tests: passed: suite/issues-sync.test.ts the issues model composes alone and binds on every dialect

FR-002checkpassing

An issue record MUST be identified by its scope and number, hold what the code says of it and a hash of that, say whether the code still has it, and have its goals, engines, evidence and links as records of their own.

Enforced (check): .github: cd commons/data && bun run verify — suite/issues-sync.test.ts: a sync adds what is new, rewrites what changed with its goals, engines, evidence and links, and records the run in a ledger

Proved by: data/suite/issues-sync.test.ts

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

Tests: passed: suite/issues-sync.test.ts a sync adds what is new, rewrites what changed with its goals, engines, evidence and links

FR-003checkpassing

syncIssues MUST add the issues that are new, rewrite those whose hash changed with their goals, engines, evidence and links, and record the run in a ledger with how many it added, changed, withdrew and reopened, all in one transaction.

Enforced (check): .github: cd commons/data && bun run verify — suite/issues-sync.test.ts: a sync adds what is new, rewrites what changed with its goals, engines, evidence and links, and records the run in a ledger

Proved by: data/suite/issues-sync.test.ts

Written in: data/sql/extensions/issues/mod.ts, data/sql/extensions/issues/sync.ts

Tests: passed: suite/issues-sync.test.ts a sync adds what is new, rewrites what changed with its goals, engines, evidence and links

FR-004checkpassing

An issue that the code no longer has MUST be marked withdrawn and never deleted, and MUST be brought back, rewritten where it changed, when the code has it again.

Enforced (check): .github: cd commons/data && bun run verify — suite/issues-sync.test.ts: an issue the code no longer has is withdrawn and never deleted, and comes back, rewritten where it changed, when the code has it again

Proved by: data/suite/issues-sync.test.ts

Written in: data/sql/extensions/issues/sync.ts

Tests: passed: suite/issues-sync.test.ts an issue the code no longer has is withdrawn and never deleted, and comes back, rewritten

FR-005checkpassing

Where the records already match the code a sync MUST write nothing (unless it is told to record the run); a failure MUST roll back everything it did and be an error as a value.

Enforced (check): .github: cd commons/data && bun run verify — suite/issues-sync.test.ts: a sync of records that already match writes nothing, and a failure rolls back everything it did and is a value

Proved by: data/suite/issues-sync.test.ts

Written in: data/sql/extensions/issues/sync.ts

Tests: passed: suite/issues-sync.test.ts a sync of records that already match writes nothing, and a failure rolls back everything i

Out of scope

  • Writing the code from the database: the code is the source of truth, per FR-003.
  • DuckDB: it cannot update a row that others refer to, so the sync is for the engines that can.

Edge cases

  • Two scopes in one sync: each scope is judged alone and the run is one transaction, per FR-003.
  • An issue whose links point at one that is new: the links are written after every issue, per FR-003.

Assumptions

  • A project that wants the model lists issuesModule to composeModules, alone or with others.

Open questions

OQ-1open question

Whether a sync should also read who closed an issue from the commit that did it.

Key entities

  • Issue record - one issue in the database.
  • Sync run - one row of the ledger.

Success criteria

SC-001success criterion

The records of a database match the issues of the code after a sync, and the sync does nothing when they already match.

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/issues/mod, sql/extensions/issues/sync, Planning, Issues as typed code

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