Integrations logical ports 0003 Active
0003-integrations-logical · owner if · domain commons
Input
The ports of Integrations are typed interfaces, each a record of functions, that the pure cores are written against and the physical layer implements: the credential port (a reference in, a secret that cannot be printed out), the read port (it can only read), the clock and the trace. No core reads the time, a file or a network.
# PortsA 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
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
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 scenariosGiven a secret with the value abc123xyz, When it is turned into JSON, Then the text is "[secret]", per FR-002 .# Out of scope# Edge casesA Secret that is spread into an object: its functions are not data, JSON.stringify still says [secret], per FR-002 . # AssumptionsA runtime cannot stop a program that calls reveal and prints it; the port makes the accident impossible, not the malice. # Open questions# Key entitiesPort - a record of functions.Secret - an opaque value.# Success criteriaA 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 byIntegrations , logical/constraints , logical/ports