Entity / Operators

Testing operator laws and parity

Declare algebraic laws (Law.associative, Law.identity, Law.preservesCollation) on primitive operators and verify them with Conformance:

ts
import { Law } from 'foldkit-entity'
import { Conformance } from 'foldkit-entity/conformance'

const concat = Expr.operator('acme.concat', {
  input: [Schema.String, Schema.String],
  output: Schema.String,
  collation: 'operands',
  laws: [Law.associative, Law.identity(''), Law.preservesCollation],
})
const concatMemory = Operators.memory(
  Operators.implement(concat, (left, right) => `${left}${right}`),
)

const verdict = Conformance.laws(concat, concatMemory)
const recorded =
  verdict._tag === 'Holds' ? Operators.withEvidence(concatMemory, verdict.evidence) : concatMemory

const report = await Conformance.operator(concat, {
  implementations: { memory: Conformance.memory(concatMemory) },
})
  • Sampling checks: Conformance.laws tests edge inputs (empty strings, mixed case, astral Unicode, zero, negatives, fractions) and returns Counterexample when a law fails (for instance, concat fails commutativity on "a" and "A").
  • Per-table evidence: Attach Conformance.laws evidence to memory tables and Conformance.lawsBy evidence to SQL tables; overriding an implementation clears its evidence automatically.
  • Cross-backend parity: Pass both memory and SQL runners to Conformance.operator to verify matching results and refusals across every edge case.

Publishing what a server runs

Operators.describe(op) and Operators.describeTable(table) emit JSON-Schema metadata (ID, version, input/output schemas, null and collation rules, laws, and attached evidence, omitting internal definedAs bodies) validated by OperatorDescription.

Versions form part of the operator's identity: a table providing acme.slug (v1) refuses a query calling acme.slug@2 with acme.slug@2 (this table has acme.slug) so client/server deploy skew surfaces immediately.