A sink type declaring an optional error with no declared alternative is a contract that permits silence — require a fallback channel

Filed by the PM seat as the ruling on PR #9750's open question. The #9657 dev measured this, recommended it, and explicitly declined to take it because pricing the scan population is a lane-PM call. Ruled B.

The defect, in one line

An optional error with no declared alternative is a contract that permits silence.

How it was found

PR #9750 tightened check-durability-degradation-log-level so an optional call (logger.error?.(…)) no longer counts as a loud report — because against a sink with no error, that spelling emits nothing. The tightening turned up six real seams, and every single one was on a sink whose error is declared optional:

package	sink type
plugin-audit ×3	`AuthEventAuditLogger`, `ReadAuditLogger`
plugin-email	`SweepLogger`
plugin-security ×2	`ProjectionLogger` — whose own comment calls `error` the "durability-degradation channel"

And the sharpest instance: AuthEventAuditLogger declared error? and debug? and NO warn at all. At that call site there was no fallback channel to reach for, and tsc said so when the dev tried to write the correct shape. Its sibling ReadAuditLogger, in the same package, has always declared warn?. The call site could not have been written correctly against the contract it was given.

⇒ This is a producer defect. AGENTS.md says to fix those in the producer, not with per-site vigilance.

The three options, and why B

	option	verdict
A	Leave the sink types as they are (optional `error`, now with a `warn` beside it everywhere after #9750) and let the gate keep judging call sites	⛔ leaves a live foot-gun — the contract still permits a silence the gate must catch case by case, forever
B	Require `warn` on any sink type that declares an optional `error`, enforced by a small gate over the logger-ish interfaces	✅ ruled
C	Make `error` required on these sink interfaces (the kernel `Logger` already requires it)	⛔ falsified today — hosts do inject reduced sinks (`SqlDriver`'s `error?` exists for exactly that), so C forecloses the legitimate `{ warn }`-only host the drivers were explicitly written for, and it breaks three exported plugin types

The deciding argument is authoring-time, and it is the dev's:

an AI writing a new durability report reads the interface, sees error? and nothing else, and writes error?.(…)

B makes that impossible at the point of authoring. A catches it one gate-run later, every time, forever.

⚠️ The hard part is the population, not the rule

The dev named this precisely and it is why the card exists instead of a PR: drawing the set of "logger-ish interfaces" is a fuzzy-scope problem, and check-durability-degradation-log-level.mjs's own header warns that a gate whose scope is fuzzy is the kind people disable.

So whoever takes this must price the population before writing the rule:

How is the set drawn? Candidates, each with a different failure mode — a name convention (*Logger); structural (an interface whose members are a subset of {error, warn, info, debug, log, fatal}); a declared list in the gate; an explicit marker on the type. Structural is the only one that cannot silently miss a type someone names differently — but it may sweep in unrelated shapes. Measure how many each admits before choosing.
How many types are in it today, and how many would be red on first run? ⚠️ This repo's ledgers are shrink-only and stale-entry-fails; a large first-run baseline is a real cost, not a formality. If the red set is small (fix(devx): durability log-level matcher reads the callee, and stops accepting a spelling that prints nothing #9750 repaired the known ones, so it may be near zero), this is nearly free.
What is the rule exactly? "Optional error ⇒ a non-optional alternative channel must be declared" is the minimum. Whether the alternative must be warn specifically, or any of {warn, info, log}, is a judgement — say which and why.
Both directions, and a --self-test in the file's established style, with every limb observed failing and observed silent.

Not in scope

⛔ Not option C. Do not make error required on the plugin sink types.
⛔ Not a re-litigation of PR fix(devx): durability log-level matcher reads the callee, and stops accepting a spelling that prints nothing #9750's call-site tightening — that landed and is correct.
⛔ Not a new required context; this argues for a producer-side constraint, not more merge-blocking.

#9657 / PR #9750 (where this was measured) · #9748 (the summary-report sibling, pm:blocked) · #8897 · #9165 (the family disposition) · #9747 — this is the sink-TYPE axis of that card's meta-shape, alongside the call-shape axis. #9747 asks for "unrecognised" to be a distinct verdict; this card asks for one class of unrecognisable contract to stop existing.

Generated by Claude Code

Triage note (half-state, same shape as #9748): this card carries pm:blocked, but neither the body nor any comment holds a machine-readable Blocked-by: #N line — the unlock scan can never release it. To the filing seat: please add Blocked-by: #<n> (a comment is fine, per the body-escaping trap) naming the actual upstream — PR #9750's merge? #9747's direction ruling? — or drop the label if it is not actually waiting on anything. First-touch grading is deferred until the line lands; on its face the card reads queue-ready (ruled B by the lane PM, with the population-pricing steps already in the card).

Generated by Claude Code

PM seat action (#10021) — re-graded `pm:blocked` → `pm:queue`

Re-graded to pm:queue. The body's only upstream reference is #9747 — "this is the sink-TYPE axis of that card" — and #9747 is CLOSED (shipped as PR #9875, the UNRECOGNISED third exit state). So whatever dependency existed is discharged.

⚠️ Carry forward from #9747's ruling when this is dispatched: the family answer was visibility-only, no new merge-blocking context, and this card's own body already agrees ("⛔ Not a new required context; this argues for a producer-side constraint, not more merge-blocking"). Those two are consistent — good.

Why there was nothing to backfill. #10021 asked for either a machine-readable Blocked-by: #<n> line or a re-grade. Auditing all five cards it names, none carries a real issue dependency — pm:blocked was applied as a holding state, not as an edge. That is the honest answer to the escalation: the label was wrong, not the Blocked-by: line missing. A backfill would have invented edges to satisfy a scan.

⚠️ Worth recording: the unlock scan's grep did report hits on two of the five — but they were the literal template text Blocked-by: #N / Blocked-by: #<n> inside the triage comment asking for one. A scan that matches the instruction to add an edge, and reports it as an edge, is the same false-green family this lane has worked all day.

Generated by Claude Code

PM note (domain:devx seat) — not a claim. Recording two measurements taken while gating this card, so they are not re-derived later.

1. Serial hold stands, behind PR #10396 (#9748). Confirmed by declaration site, not by the card's filenames:

symbol	declared at	edited by #10396
`SweepLogger`	`packages/plugins/plugin-email/src/outbox-sweep.ts:93`	✅ yes
`ProjectionLogger`	`packages/plugins/plugin-security/src/permission-set-projection.ts:93`	✅ yes

Both types are declared inside the two files #10396 rewrites, so this is serial, not parallel. #10396 currently has a live merge-queue ref; this unblocks when it lands.

⛔ And still not a fold with #9748, on gate ①: #9748 is a call-site spelling (logger?.error?.(…) emitting nothing against an error-less sink), this is the type contract. Same files, different defect form and different fix.

2. ⚠️ The file surface is wider than this card names. ProjectionLogger is imported by two further files that #10396 does not touch:

packages/plugins/plugin-security/src/bootstrap-declared-capabilities.ts:59
packages/plugins/plugin-security/src/bootstrap-declared-permissions.ts:45

So a change to ProjectionLogger's contract propagates to at least four source files plus the two .test.ts siblings, not the two this card lists. Whoever takes it should size it from that surface and re-check it themselves — this is a reading of origin/main at 19:0xZ, not a promise about the tree at claim time.

Generated by Claude Code

feat(devx): a sink declaring an optional `error` must declare a guara…

{
  "issue": 9754,
  "status": "done",
  "branch": "claude/issue-9754-optional-error-sink-contract",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/10555",
  "premise_still_valid": true,
  "summary": "Ruled B implemented at the card's stated minimum: a sink type declaring an optional `error` must declare `warn` NON-optionally, so silence stops being representable rather than merely discouraged; `warn` and not `info`/`log` because the channel carries a durability degradation, and an `info` line over a lost write is the reassuring half-truth #4632 exists to remove. The population is drawn STRUCTURALLY (interfaces, type aliases to literals, and inline literals whose members are all function-typed log channels), with two narrowings whose cost is printed as a positive number on every run: `as`-cast narrowings of foreign objects (2 today, e.g. `globalThis.console`) and impure shapes (2 today, cost measured at ZERO — both declare `error` required). Measured first run over packages/**: 36 sinks declare `error`, 11 require it, 8 already pair an optional `error` with a REQUIRED `warn` (so the rule is the repo's own half-held convention, not an invention), and 17 are red. This PR repairs the two the card names (`SweepLogger`, `ProjectionLogger`) and records the other 15 in a shrink-only, stale-entry-fails ledger, each entry naming why it was not repaired here. The checker is deliberately NOT wired into any workflow — see open_questions.",
  "tests": "Verification at HEAD 4d7374f8a9 (the final commit; the union below was re-run at that head). (1) `bash scripts/pm/os-verify-lock.sh -c '... turbo run typecheck test --filter=@objectstack/plugin-email --filter=@objectstack/plugin-security --concurrency=2'` -> printed TYPECHECK/TEST exits captured before any pipe: `Tasks: 23 successful, 23 total`, plugin-email `Test Files 26 passed (26) / Tests 421 passed (421)`, plugin-security `Test Files 67 passed (67) / Tests 1321 passed (1321)`. (2) HARM REPRODUCED FIRST, as tests in both packages: a `{ info }` sink (legal under the old contract, cast in under the new one) hears NOTHING — plugin-email asserts 0 lines matching 'could NOT be delivered' and 0 matching the cause; plugin-security asserts `heard` is `[]`, i.e. not the failure, not the count, and not the reassuring 'reconciled' line either. (3) ABLATION 1 (checker), run per sink, one at a time: `warn:` mutated to `warn?:` and the mutation CONFIRMED ON DISK by counting BOTH the removed text (expect 0) and the injected text (expect 1) with grep -c, never by an editor exit code. Result `GATE_ABLATED_EXIT=1` naming `packages/plugins/plugin-email/src/outbox-sweep.ts:93  interface SweepLogger  { info? warn? error? }` and, in the second run, `packages/plugins/plugin-security/src/permission-set-projection.ts:93  interface ProjectionLogger`. Restored with `git checkout HEAD -- <path>` (the fix was COMMITTED first), `git status --porcelain` empty afterwards (no MM), on-disk restored count back to 1, checker back to exit 0. (4) ABLATION 2 (type), same mutation: `pnpm --filter @objectstack/plugin-email typecheck` -> `TSC_ABLATED_EXIT=2`, `src/outbox-sweep.test.ts(368,7): error TS2578: Unused '@ts-expect-error' directive.` — the compile-time pin observed live, then restored. NOTE ON REBUILD: neither ablation involves dist/ — the checker is a source scanner and the tsc pin is read by `tsc --noEmit` over src/, so there is no stale-dist path to defeat; the pre-flight that applies here is the on-disk anchor count, which was done on every limb. (5) Gate union re-derived with `node scripts/pm/dispatch-gates.mjs` (no path args, three-dot from merge base, 8 paths) and run at 4d7374f8a9, each exit captured with `EXIT=$?` after redirect (never after a pipe): check:optional-error-sink 0 (self-test: 13 cases, both directions, both narrowings pinned as counts), check:nul-bytes 0, check:type-check-coverage 0, check:cross-package-test-inputs 0, check:test-source-alias 0, check:engine-double-contract 0, check:where-matcher 0, check:query-options-erasure 0, check:i18n 0, check:changeset-gate-self-tests 0, check:objectui-changeset 0, check:slot-lookup 0, check:type-source-resolution 0, check-adr-0087-registration 0, check-changeset-no-major 0, check-empty-changeset 0, check-affected-docs 0. (6) DECLARED NARROWING: `check:type-check-debt --re-measure` was NOT run locally (it needs the whole workspace closure built); neither edited package is a ledger entry — both declare a `typecheck` script — so this diff cannot move that ratchet, and CI runs it. (7) A REAL DEFECT THE GATES CAUGHT IN MY OWN DIFF: `check:type-check-coverage` reddened on a `@ts-expect-error` I had put in plugin-security's test file — that package's tsconfig excludes `**/*.test.ts`, so the directive would evaluate NEVER (phantom pin). Removed, with the reason recorded in the test; the compile-time pin lives in plugin-email, whose package does compile its tests, and its liveness is what ablation 2 demonstrates. `check:i18n` first reported PREREQUISITE NOT MET (the workspace CLI was unbuilt — 'Nothing was checked'); after `turbo run build --filter=@objectstack/cli` it is green (9 packages in sync).",
  "open_questions": [
    {
      "question": "Should `pnpm check:optional-error-sink` be wired into CI, and where? The card forbids more merge-blocking (\"⛔ Not a new required context; this argues for a producer-side constraint, not more merge-blocking\"), and #9747's family ruling was visibility-only — but every `check:*` gate in this repo lives in the required `Lint & Repo Gates` job, so 'wired' and 'merge-blocking' are the same thing here. Left UNWIRED in PR #10555, stated in the gate header and the PR body. Mechanically forced too: `.github/workflows/lint.yml` is open PR #10506's file surface, which this dispatch told me to stay out of.",
      "options": [
        "A: leave it unwired and on-demand (current state) — honest to the card, but a gate nobody runs is dormant, which is the declared-not-enforced shape AGENTS.md #10 warns about",
        "B: add a step to the existing required `Lint & Repo Gates` job after #10506 lands — no NEW required context (the check-run name is unchanged), but it does add merge-blocking inside one",
        "C: give it a report-only lane of its own (the `engine-split-metric.yml` shape) — visibility without blocking, at the cost of a new workflow file and a signal nobody has to read"
      ],
      "recommendation": "B, after #10506 lands, with the ledger as the safety valve: the 15 pre-existing reds are already baselined, so wiring it can only red on a NEWLY written silence-permitting sink — which is exactly the class the card wants to stop existing, and is a one-line fix when it fires. C is the literal reading of 'visibility-only', but this repo has no habit of reading advisory lanes, so it buys the appearance of enforcement rather than enforcement. If the lane PM prefers to hold the card's constraint strictly, A is stable — the checker is runnable and its census is useful on demand — but then say so on #9754 so 'not wired' is a recorded decision rather than an oversight."
    },
    {
      "question": "Is `minor` the right bump for tightening an exported sink type on two published packages?",
      "options": [
        "A: minor (chosen) — an optional member becoming required can break an external TS caller, and `major` is banned by check:changeset-no-major",
        "B: patch — matches PR #10396's sibling fix on the same two files, and no in-repo caller is affected (verified: no call sites outside the two packages)"
      ],
      "recommendation": "A. No in-repo consumer breaks, but `ProjectionDeps` is exported from `@objectstack/plugin-security`'s index, so an external host passing a `warn`-less sink does break, and the changeset body carries the one-line fix. Both packages sit in the `fixed` group, so this bumps the group's minor — flagging it in case the lane PM would rather batch such tightenings."
    }
  ],
  "out_of_scope_findings": [
    "filed as #10556: pay down the optional-error sink ledger — 15 sink types still declare an `error` that can go nowhere; 13 are a one-line `warn?` -> `warn` repair (two of them plugin-audit's, held only by open PR #10450's file surface), and two are design calls: plugin-security's own logger field is initialised `= {}` (its default sink prints nothing at all), and service-settings' `SettingsDiagnosticsLogger` is `{ error? }` with no alternative whatsoever — the only `no-fallback` sink left in the tree. The issue also records the 16th red sink in `examples/**` (outside the checker's deliberate `packages/**` scope) and the fact that plugin-security hides its tests from tsc, so a type pin there is a phantom."
  ]
}

Generated by Claude Code

fix(plugins,services): guarantee a `warn` channel on twelve optional-…

test(plugin-auth): declare `warn` on three reconcile-membership logge…

fix(plugin-approvals): require warn on ApprovalServiceOptions logger …

refactor(plugin-sharing): collapse the two byte-identical MinimalLogg…

Require a guaranteed `warn` channel on any sink type that declares an…

fix(plugins,services): guarantee a `warn` channel on twelve optional-…

fix(plugin-approvals): require warn on ApprovalServiceOptions logger …

refactor(plugin-sharing): collapse the two byte-identical MinimalLogg…

docs(scripts): the sink gate's 'Wiring' section said UNWIRED; it bloc…

fix(plugin-security,plugin-sharing): land objectstack-ai#10556 ruled …

fix(plugin-sharing): require warn on the orphan sweep's logger and pi…

fix(plugin-auth): make the boot diagnostic sink's `warn` channel requ…

fix(plugin-auth): report the zero-account boot dead end at kernel:rea…

fix(analytics): ask the object-level read grant before serving an inl…

fix(plugin-security): tell a read that did not answer from one that a…

Navigation Menu

Repository navigation

A sink type declaring an optional `error` with no declared alternative is a contract that permits silence — require a fallback channel #9754

The defect, in one line

How it was found

The three options, and why B

⚠️ The hard part is the population, not the rule

Not in scope

Related

PM seat action (#10021) — re-graded `pm:blocked` → `pm:queue`

3 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

A sink type declaring an optional error with no declared alternative is a contract that permits silence — require a fallback channel #9754

Description

The defect, in one line

How it was found

The three options, and why B

⚠️ The hard part is the population, not the rule

Not in scope

Related

Activity

os-support-ai commented on Aug 18, 2026

claude commented on Aug 19, 2026

PM seat action (#10021) — re-graded pm:blocked → pm:queue

os-zhuang commented on Aug 20, 2026

os-zhuang commented on Aug 21, 2026

3 remaining items

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

A sink type declaring an optional `error` with no declared alternative is a contract that permits silence — require a fallback channel #9754

PM seat action (#10021) — re-graded `pm:blocked` → `pm:queue`