IF Commons GitHub

Operations

0031Active

0031-operations · owner if · domain data

The contract

FR-001checkpassing

operation MUST make a contract, frozen, from a name and a specification: a definition, whether it is a command or a query, its inputs (each text, integer, number, boolean, instant or textList, and whether it may be left out), the concepts it reads and writes by name, the permission it requires (resource:action) and the input that holds the tenant it is required in, what it emits to the audit trail (subject.verb), whether it runs as its caller or as the service, and whether doing it twice leaves the same state.

Enforced (check): .github: cd commons/data && bun run verify — suite/operations.test.ts: a contract is frozen, and the lint finds a concept that is not there, a query that writes, a bad permission or action, a scope that is not an input, a duplicate, a restricted write as the caller and a silent command

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

Written in: data/governance/operation.ts

Tests: passed: suite/operations.test.ts a contract is frozen, and the lint finds a concept that is not there, a query that writes,

FR-002checkpassing

lintOperations MUST find, against the domain, a concept a contract names that the domain does not have, a query that says it writes, a permission or an audit action that is not of its form, a scope that is not an input, two operations with one name, a command that writes a concept classified restricted and runs as its caller (it must run as the service), and, as a warning, a command that writes and says it records nothing.

Enforced (check): .github: cd commons/data && bun run verify — suite/operations.test.ts: a contract is frozen, and the lint finds a concept that is not there, a query that writes, a bad permission or action, a scope that is not an input, a duplicate, a restricted write as the caller and a silent command

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

Written in: data/governance/operation.ts

Tests: passed: suite/operations.test.ts a contract is frozen, and the lint finds a concept that is not there, a query that writes,

The runtime

FR-003checkpassing

operations MUST make a runtime from the logical schema, a dialect, a driver, the contracts and an implementation of each by name, and MUST give errors as values for a contract with no implementation, an implementation with no contract, a table that a contract names and the schema does not have, a contract that requires a permission when no authorizer is given, and one that emits when no audit trail is given.

Enforced (check): .github: cd commons/data && bun run verify — suite/operations.test.ts: a runtime needs an implementation for each contract, a contract for each implementation, tables the schema has, and an authorizer and an audit trail where the contract asks for them

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

Written in: data/sql/extensions/operations/mod.ts, data/sql/extensions/operations/runtime.ts, data/sql/extensions/operations/tx.ts

Tests: passed: suite/operations.test.ts a runtime needs an implementation for each contract, a contract for each implementation, t

FR-004checkpassing

An implementation MUST be given a transaction of typed row operations (insert, update and remove, with the number of rows changed; select, count, and a read written from the names), whose tables and columns are named by the words of their names (a column that holds a relationship by the key of the relationship), written by the naming layer for the dialect and the schema, whose values enter only as literals that the dialect writes, and which notes every table that was written; a query MUST NOT be able to write.

Enforced (check): .github: cd commons/data && bun run verify — suite/operations.test.ts: on three engines typed row operations work by the words of names and a query cannot write, and input that is missing, unknown or of the wrong type is refused before anything is done

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

Written in: data/sql/extensions/operations/runtime.ts, data/sql/extensions/operations/tx.ts

Tests: passed: suite/operations.test.ts on three engines typed row operations work by the words of names and a query cannot write,

Open: issue sql/extensions/operations 00006: Rows in operations are untyped

FR-005checkpassing

run MUST check the input against the contract and give, as errors as values, an input that is missing, one that is not a declared input and one of the wrong type, and MUST do nothing of the operation until the input is right.

Enforced (check): .github: cd commons/data && bun run verify — suite/operations.test.ts: on three engines typed row operations work by the words of names and a query cannot write, and input that is missing, unknown or of the wrong type is refused before anything is done

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

Written in: data/sql/extensions/operations/runtime.ts

Tests: passed: suite/operations.test.ts on three engines typed row operations work by the words of names and a query cannot write,

FR-006checkpassing

Where a contract requires a permission, run MUST ask the authorizer of the project whether the caller holds it in the tenant the scope input names, and where it does not (or there is no caller) MUST return the status denied and MUST record the attempt in the audit trail as an event of the first action the contract emits, with the outcome denied, and commit that record alone.

Enforced (check): .github: cd commons/data && bun run verify — suite/operations.test.ts: a caller without the permission gets denied, and the attempt is recorded and kept alone

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

Written in: data/sql/extensions/operations/runtime.ts

Tests: passed: suite/operations.test.ts a caller without the permission gets denied, and the attempt is recorded and kept alone

FR-007checkpassing

run MUST run an implementation in one transaction; commit what it did where its outcome does not say otherwise (so that an outcome that must be kept, such as a revocation, is kept and returned); and roll back, giving an error value, where it throws, where it wrote a table its contract does not name, and where it wrote and did not record in the audit trail any action its contract emits.

Enforced (check): .github: cd commons/data && bun run verify — suite/operations.test.ts: an operation is one transaction: a refusal writes nothing and is not an error, a throw and a write outside the contract and a write with no audit record roll back, and an outcome that must be kept is kept

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

Written in: data/sql/extensions/operations/runtime.ts

Tests: passed: suite/operations.test.ts an operation is one transaction: a refusal writes nothing and is not an error, a throw and

FR-008checkpassing

A query MUST be run in a transaction that is rolled back; and the context an operation is given (the clock, identifiers, tokens, the hash of a token and of an identifier, the check of a password, who is acting) MUST have defaults that need no secret (a password verifier is the application's) and be replaceable, so that a test is the same every time.

Enforced (check): .github: cd commons/data && bun run verify — suite/operations.test.ts: on three engines typed row operations work by the words of names and a query cannot write, and input that is missing, unknown or of the wrong type is refused before anything is done

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

Written in: data/sql/extensions/operations/runtime.ts

Tests: passed: suite/operations.test.ts on three engines typed row operations work by the words of names and a query cannot write,

FR-009checkpassing

An operation MUST say how it is decided who may call it, as exactly one of: a permission it requires, that it is public, or what its implementation checks (checkedBy, in words); the lint MUST find one that says none or more than one, and a runtime MUST NOT be made for one that says none, so that a contract that forgot its permission is never a contract that anyone may call.

Enforced (check): .github: cd commons/data && bun run verify — suite/operations.test.ts: an operation requires a permission or says it is public, and a contract that does neither is found by the lint and refused by the runtime

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

Tests: passed: suite/operations.test.ts an operation requires a permission or says it is public, and a contract that does neither

Cited by: governance/operation

Out of scope

  • A server or a protocol: the runtime is a function; an HTTP or RPC layer wraps it.
  • A generated typed client, and a check that a client's state is the database's: a later specification.
  • Operations as stored procedures or functions in a database: an opt-in, a later specification.
  • Concurrency across connections: the tests cannot show it on these engines; the single conditional statement of an operation, not the application, decides who wins.

Edge cases

  • DuckDB cannot update a row that another row refers to (its foreign key limitation, which it reports as an error): an operation that does so fails there as a value, per FR-007; PostgreSQL and SQLite are the engines for operations that change rows others refer to.
  • An operation that writes nothing because its outcome is a refusal (slug-taken): not an error, and records nothing, per FR-007.
  • An operation that throws after writing: nothing it did stays, per FR-007.
  • A denied call to a query: nothing is recorded; it is rolled back, per FR-006.

Assumptions

  • The database's transactions include its DDL and are the unit of an operation.
  • The authorizer and the audit sink are the model's (the identity model's are in 0032).

Open questions

OQ-1open question

Whether the driver should take bound parameters, so that no value is ever a literal in SQL text.

Key entities

  • Operation - a contract: what it takes, reads, writes, needs and records.
  • Runtime - what runs operations in one transaction and holds them to their contracts.
  • Outcome - the status an operation gives, with what goes with it.

Success criteria

SC-001success criterion

The business operations of a model are written once, behave the same on every engine, and cannot write what they did not say or leave no trace of what they did.

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

governance/operation, Data, sql/extensions/operations/runtime, sql/extensions/operations/tx

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