IF Commons GitHub

Integrations verbs

0009Active

0009-integrations-verbs · owner if · domain commons

The verbs

FR-001checkpassing

The surface MUST give the verbs observe, probe, check, validate, translate, send, receive and explain, built from Deps, a record of ports (connectors and their read ports, plugins, schemas, agreements, files, transports and the clock), so that a verb is a function of its ports and a test runs it over in-memory ones.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/verbs.test.ts: each verb runs over in-memory ports

Proved by: integrations/suite/verbs.test.ts

Written in: integrations/src/surfaces/headless/mod.ts

Tests: passed: suite/verbs.test.ts each verb runs over in-memory ports

FR-002checkpassing

Each verb MUST declare its action and a reach policy: the reading verbs report and read-only on every channel; translate, send and receive actions that change something and are not reachable over ssh.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/verbs.test.ts: reach policies conform

Proved by: integrations/suite/verbs.test.ts

Written in: integrations/src/surfaces/headless/mod.ts

Tests: passed: suite/verbs.test.ts reach policies conform

FR-003checkpassing

No verb over a document MUST say a value of the payload in its text, its data, its problems or its hints: the outcome MUST be redacted over the values of the tree, and a test MUST show a payload value absent from the JSON of every such verb.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/verbs.test.ts: no payload value in the outcome of any verb over a document

Proved by: integrations/suite/verbs.test.ts

Written in: integrations/src/surfaces/headless/mod.ts

Tests: passed: suite/verbs.test.ts no payload value in the outcome of any verb over a document

FR-004checkpassing

explain MUST say one sentence for each finding code and refuse a code it does not know.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/verbs.test.ts: explain covers every code

Proved by: integrations/suite/verbs.test.ts

Written in: integrations/src/surfaces/headless/mod.ts

Tests: passed: suite/verbs.test.ts explain covers every code

FR-005checkpassing

A missing credential MUST be a pending problem naming the reference (never a value), an unreached partner a failure with the kind, and a send MUST leave the exchange in the state the transition function gives.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/verbs.test.ts: credential, delivery and state

Proved by: integrations/suite/verbs.test.ts

Written in: integrations/src/surfaces/headless/mod.ts

Tests: passed: suite/verbs.test.ts credential, delivery and state

Acceptance scenarios

  1. Given a document whose patient name is Zyxwvut, When validate runs and finds a problem there, Then Zyxwvut is not in the outcome, per FR-003.

Out of scope

  • The tool server and REST surfaces; the process entry that wires real ports.

Edge cases

  • A code explain does not know: a failure naming it, per FR-004.

Assumptions

  • Deps are wired at the edge by the program that draws the verbs.

Open questions

  • None.

Key entities

  • Verb - a command of Headless.
  • Deps - the ports a verb needs.

Success criteria

SC-001success criterion

The same verbs run here and anywhere, and say nothing of a payload.

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

Integrations, surfaces/headless/mod

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