IF Commons GitHub

Integrations logical ports

0003Active

0003-integrations-logical · owner if · domain commons

Ports

FR-001checkpassing

A port MUST be a typed record of functions (CredentialPort, ReadPort, Clock, Trace); a core MUST take what it needs as a port and MUST NOT reach the clock, a file or a network itself.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: a connector observes over an in-memory port and a fixed clock

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

Written in: integrations/src/logical/ports.ts

Tests: passed: suite/observe.test.ts a connector observes over an in-memory port and a fixed clock, and describe agrees with go

FR-002checkpassing

A Secret MUST say [secret] however it is turned into text (toString, toJSON, a template, JSON.stringify) and give its value only to reveal; the credential port MUST hand out a Secret, and the read port MUST have no way to write.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: a secret never shows in text or JSON

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

Written in: integrations/src/logical/ports.ts

Tests: passed: suite/observe.test.ts a secret never shows in text or JSON

FR-003checkpassing

A trace event MUST carry only identities, counts and codes, never a payload; findings and failures MUST carry paths, kinds and statuses, never values.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: findings and failures hold no value of the payload

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

Written in: integrations/src/logical/ports.ts

Tests: passed: suite/observe.test.ts findings and failures hold no value of the payload

Cited by: logical/constraints, logical/ports

Acceptance scenarios

  1. Given a secret with the value abc123xyz, When it is turned into JSON, Then the text is "[secret]", per FR-002.

Out of scope

Edge cases

  • A Secret that is spread into an object: its functions are not data, JSON.stringify still says [secret], per FR-002.

Assumptions

  • A runtime cannot stop a program that calls reveal and prints it; the port makes the accident impossible, not the malice.

Open questions

  • None.

Key entities

  • Port - a record of functions.
  • Secret - an opaque value.

Success criteria

SC-001success criterion

A credential never appears in a log, a JSON document or an error by accident.

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, logical/constraints, logical/ports

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