FactoryWager Wiki

Wire boundary (parse once)

JIT: Parse-once / unknown / brands at the edge. Unresolved → this file only.

SSOT for untrusted → trusted domain values. Code: config/eslint/plugin-harness/boundary.ts · brands: lib/types/branded/README.md · thesis: parse, don’t validate.

Principle

wire / CLI / env / JSON / HTTP
        →  BOUNDARY (parse* · decode* · is* · unknown OK)
        →  INTERIOR (brands / domain types only — no unknown args, no re-decode)

Boundary (where `unknown` / decode OK)

Kind	SSOT
Paths	`BOUNDARY_PATH_RE` — `lib/types/branded/`, `/boundary\|wire\|ingress/*`, `boundary\|wire\|ingress*.ts`, `lib/security/r2-credentials.ts`
Names	`BOUNDARY_FN_NAME_RE` — `parse` · `decode` · `assert` · `is` · `from` · `FromUnknown\|Wire\|Json\|Env`
Guards	`(v: unknown) => v is T`

Interior (not allowed)

Ban	Prefer
`function f(x: unknown)`	brands / concrete types
`decodeUnknown*` mid-stack	call named `parse*` at the edge
bare `sessionId: string`	`SessionId` + `parse` / `as` / `try*`

Rules

Rule	Severity
`harness/no-decode-unknown-outside-boundary`	error
`harness/no-unknown-function-param`	warn harness · error types/security/core/boundary
`branded-id-check --staged --strict`	error on new bare `*Id` / opaque `id` without `// brand-ok`

bun run lint:harness
bun tools/branded-id-check.ts --staged --strict
bun tools/harness-violations.ts --path lib --rule unknown

Suppress only with reason: // brand-ok or targeted eslint-disable on a true edge.

Checklist

Raw unknown/JSON only on parse* / boundary path / type guard
Emit brands/structs from that edge
Interior uses brands only
No decodeUnknownSync outside the edge

Spine parse examples: parseImageEvidenceMeta / isImageEvidenceMeta in lib/image-metadata.ts — wire JSON → ImageEvidenceMeta (TEST-003 evidence) via parse* / is* name rules; no extra path allowlist.

Package imports ≠ wire: IMPORT_BOUNDARIES.md. Install ≠ wire: UNIFIED.md.

This site is open source. Improve this page.