fix(notices): keep the byte bound on egress; fail closed on library limits; bounded-history wording

Self-review findings: a redacted document that grew past the Agent Document
byte bound is handed out as the placeholder; RedactionLimitError falls back
to the mark instead of failing the inbox; the pinned detectors' assignment
and OpenAI length limits are documented as contract; the generated notice
page no longer calls the ledger append-only.

Author: ScriptedAlchemy

.changeset/99-notice-redaction-retention.md

@@ -3,4 +3,4 @@
 "agent-bundle": minor
 ---
 
-Close out #99 acceptance item 7 with a notice redaction contract and a retention policy. `notices.publish()` accepts `sensitivity: 'public' | 'internal' | 'secret'` (default `internal`); each host's `noticeDelivery` row may name a dated `sensitivity` ceiling, and the ledger, inbox resource (`agent-bundle://notices/inbox`, which now reports `sensitivity` and `disclosure`), event admission, and `resources/updated` signaller withhold a notice above the route's ceiling, recording the refusal as `withheld[route]` on the notice; `internal` content is redacted on every route by `flare-redact@1.6.1`, a new exact-pinned runtime dependency of `@agent-bundle/runtime` (default detectors — provider tokens, JWTs, PEM keys, `Bearer`/`Basic` headers, URL credentials, credential assignments, e-mail addresses, cards — plus credential-shaped member names, every finding replaced whole by `[REDACTED]`; `redactSecretText`, `redactNoticeDocument`, `containsSecretText`, `resolveNoticeDisclosure`, `AGENT_NOTICE_ROUTE_SHAPES` from `@agent-bundle/runtime/notices`). `notices.retention: { terminalTtl, maxTerminal, maxJournalBytes }` in `agent-bundle.config.ts` (validated as `AB4833`, shown by `inspect --state` and the Workbench State panel) prunes settled terminal notices on admitted events and compacts the ledger journal past its byte bound through the new `AgentNoticeLedger.retain()` / `inspect()` and the state kernel's `AgentStateStore.compact()` / `inspect()` (a `compact` journal record and `AgentStateChange` kind; a compacted SQLite store moves to kernel format 2). Built-in hosts admit `secret` on `current-response` / `next-event` and `internal` on `mcp-inbox` / `mcp-resource-updated` (adapter revisions bumped). Breaking: `AgentStateStore` implementations must add `compact()` and `inspect()`, `AgentNoticeLedger` gains `retain()` / `inspect()`, `AgentNoticeDelivery` gains `disclosure`, and `AgentStateChange` / `AgentStateJournalRecord` gain the `compact` kind. The aliased `mcp-server-runtime.d.ts` no longer imports from `@agent-bundle/runtime/notices` (`GeneratedNoticeDeliveryBinding` is spelled locally). (#437)
+Close out #99 acceptance item 7 with a notice redaction contract and a retention policy. `notices.publish()` accepts `sensitivity: 'public' | 'internal' | 'secret'` (default `internal`); each host's `noticeDelivery` row may name a dated `sensitivity` ceiling, and the ledger, inbox resource (`agent-bundle://notices/inbox`, which now reports `sensitivity` and `disclosure`), event admission, and `resources/updated` signaller withhold a notice above the route's ceiling, recording the refusal as `withheld[route]` on the notice; `internal` content is redacted on every route by `flare-redact@1.6.1`, a new exact-pinned runtime dependency of `@agent-bundle/runtime` (default detectors — provider tokens, JWTs, PEM keys, `Bearer`/`Basic` headers, URL credentials, credential assignments, e-mail addresses, cards — plus credential-shaped member names, every finding replaced whole by `[REDACTED]`; assignment values shorter than four characters and OpenAI keys longer than 64 characters are outside the pinned detectors — publish those as `secret`; `redactSecretText`, `redactNoticeDocument`, `containsSecretText`, `resolveNoticeDisclosure`, `AGENT_NOTICE_ROUTE_SHAPES` from `@agent-bundle/runtime/notices`). `notices.retention: { terminalTtl, maxTerminal, maxJournalBytes }` in `agent-bundle.config.ts` (validated as `AB4833`, shown by `inspect --state` and the Workbench State panel) prunes settled terminal notices on admitted events and compacts the ledger journal past its byte bound through the new `AgentNoticeLedger.retain()` / `inspect()` and the state kernel's `AgentStateStore.compact()` / `inspect()` (a `compact` journal record and `AgentStateChange` kind; a compacted SQLite store moves to kernel format 2). Built-in hosts admit `secret` on `current-response` / `next-event` and `internal` on `mcp-inbox` / `mcp-resource-updated` (adapter revisions bumped). Breaking: `AgentStateStore` implementations must add `compact()` and `inspect()`, `AgentNoticeLedger` gains `retain()` / `inspect()`, `AgentNoticeDelivery` gains `disclosure`, and `AgentStateChange` / `AgentStateJournalRecord` gain the `compact` kind. The aliased `mcp-server-runtime.d.ts` no longer imports from `@agent-bundle/runtime/notices` (`GeneratedNoticeDeliveryBinding` is spelled locally). (#437)

packages/rsc-runtime/README.md

@@ -399,11 +399,17 @@ credential-shaped member name (`password`, `token`, `apiKey`,
 `authorization`, …) is masked whole regardless of content, and member names
 themselves are scanned like any other string. Not redacted: paths (coordination
 notices legitimately name files), numbers, base64 image and audio payloads,
-and vocabulary fields (`kind`, `status`, `code`, `mimeType`). Known gap at the
-pinned version: the OpenAI detector caps at 64 key characters, so a
-project-scoped `sk-proj-…` key of production length (~160) is not recognized;
-authors pasting one should publish as `secret`, and the detector is a
-reportable upstream fix, not something to patch here. The compiler keeps its
+and vocabulary fields (`kind`, `status`, `code`, `mimeType`). Two detector
+limits at the pinned version are part of the contract, not patched here: the
+assignment detector needs a value of at least four characters (`password=abc`
+in free text is not a finding; the same value as `{ "password": "abc" }` is
+masked by member name), and the OpenAI detector caps at 64 key characters, so
+a project-scoped `sk-proj-…` key of production length (~160) is not
+recognized. Authors pasting either should publish as `secret`; both are
+reportable upstream fixes. A redacted document that has grown past the
+Agent Document byte bound (the mark is longer than the shortest values it
+replaces) is handed out as the one-line `[REDACTED]` placeholder instead, so
+the bound made at publish holds on egress. The compiler keeps its
 own, older credential pass for probe and log text
 (`packages/agent-bundle/src/core/credentials.ts`); the two are not held in
 parity, and no vendored-code notice is involved — `flare-redact` is an

packages/rsc-runtime/src/notices/index.ts

@@ -63,6 +63,7 @@ export {
   containsSecretText,
   disclosedNoticeContent,
   isNoticeSensitivity,
+  noticeRedactionPlaceholder,
   noticeTitle,
   redactNoticeDocument,
   redactSecretText,

packages/rsc-runtime/src/notices/ledger.ts

@@ -44,9 +44,9 @@ import {
 } from './contract.js';
 import {
   AGENT_NOTICE_DEFAULT_SENSITIVITY,
-  NOTICE_REDACTION_MARK,
   disclosedNoticeContent,
   isNoticeSensitivity,
+  noticeRedactionPlaceholder,
   type AgentNoticeDisclosure,
   type AgentNoticeSensitivity,
 } from './redaction.js';
@@ -151,14 +151,7 @@ const currentlyDisclosedNotice = (
       return { notice: disclosedNotice(notice, disclosure), redacted: disclosure.redacted };
     case 'withheld':
       return {
-        notice: Object.freeze({
-          ...notice,
-          content: Object.freeze({
-            root: Object.freeze({ kind: 'text' as const, text: NOTICE_REDACTION_MARK }),
-            status: notice.content.status,
-            version: notice.content.version,
-          }),
-        }),
+        notice: Object.freeze({ ...notice, content: noticeRedactionPlaceholder(notice.content) }),
         redacted: true,
       };
     default: {
@@ -406,14 +399,7 @@ const publishProgram = Effect.fnUntraced(function*(
   // replay of it) comes back with content, and that content is the caller's.
   const notice = persisted.id === prepared.id
     ? persisted
-    : Object.freeze({
-      ...persisted,
-      content: Object.freeze({
-        root: Object.freeze({ kind: 'text' as const, text: NOTICE_REDACTION_MARK }),
-        status: persisted.content.status,
-        version: persisted.content.version,
-      }),
-    });
+    : Object.freeze({ ...persisted, content: noticeRedactionPlaceholder(persisted.content) });
   return Object.freeze({
     deduped: committed.replayed || persisted.id !== prepared.id,
     notice,

packages/rsc-runtime/src/notices/redaction.ts

@@ -1,5 +1,6 @@
-import { compilePolicy } from 'flare-redact';
+import { RedactionLimitError, compilePolicy } from 'flare-redact';
 
+import { DEFAULT_AGENT_RENDER_LIMITS } from '../agent-document.js';
 import type { AgentDocumentNode, AgentDocumentSnapshot } from '../agent-document.js';
 import type { JsonValue } from '../lower-mcp.js';
 
@@ -36,7 +37,10 @@ import type { JsonValue } from '../lower-mcp.js';
  * and IBANs; a structured value stored directly under a credential-shaped
  * member name (`password`, `token`, `apiKey`, `authorization`, …) is masked
  * whole regardless of content. Paths are not redacted: coordination notices
- * legitimately name files. The compiler keeps its own, older credential pass
+ * legitimately name files. Detector limits at the pinned version are part of
+ * the contract (README, "Redaction"): an assignment value shorter than four
+ * characters and an OpenAI key longer than 64 characters are not findings.
+ * The compiler keeps its own, older credential pass
  * for probe and log text (`packages/agent-bundle/src/core/credentials.ts`);
  * the two are not held in parity.
  */
@@ -70,11 +74,26 @@ export const NOTICE_REDACTION_MARK = '[REDACTED]';
  */
 const secretPass = compilePolicy({ mask: NOTICE_REDACTION_MARK });
 
+/**
+ * The library refuses a string it cannot bound (more than 50,000 findings, or
+ * longer than 16 MiB) with `RedactionLimitError`. On egress that refusal
+ * fails closed: the value is replaced by the mark whole rather than letting
+ * one pathological notice fail the inbox for every reader.
+ */
+const failClosed = <T>(run: () => T, fallback: T): T => {
+  try {
+    return run();
+  } catch (error) {
+    if (error instanceof RedactionLimitError) return fallback;
+    throw error;
+  }
+};
+
 /** Irreversibly removes recognizable credential material from free text. */
-export const redactSecretText = (value: string): string => secretPass.redact(value);
+export const redactSecretText = (value: string): string => failClosed(() => secretPass.redact(value), NOTICE_REDACTION_MARK);
 
 /** True when the secret pass would change `value`. */
-export const containsSecretText = (value: string): boolean => !secretPass.isClean(value);
+export const containsSecretText = (value: string): boolean => failClosed(() => !secretPass.isClean(value), true);
 
 const freezeRedactedJson = (value: JsonValue): JsonValue => {
   if (value === null || typeof value !== 'object') return value;
@@ -94,7 +113,8 @@ const freezeRedactedJson = (value: JsonValue): JsonValue => {
  * other string; the result is then deep-frozen with its member names passed
  * through the same scan.
  */
-const redactJson = (value: JsonValue): JsonValue => freezeRedactedJson(secretPass.redact(value));
+const redactJson = (value: JsonValue): JsonValue =>
+  freezeRedactedJson(failClosed<JsonValue>(() => secretPass.redact(value), NOTICE_REDACTION_MARK));
 
 const redactNode = (node: AgentDocumentNode): AgentDocumentNode => {
   switch (node.kind) {
@@ -135,17 +155,39 @@ const redactNode = (node: AgentDocumentNode): AgentDocumentNode => {
 };
 
 /**
- * Applies the secret pass to every free-text field of a detached snapshot.
- * Structure, node count, status, and codes are unchanged, so the result still
- * satisfies the Agent Document bounds the original passed; a string only ever
- * shrinks or is replaced by the fixed mark.
+ * The document a route hands out in place of content it may not disclose:
+ * one text node carrying the mark, with the original status and version.
  */
-export const redactNoticeDocument = (snapshot: AgentDocumentSnapshot): AgentDocumentSnapshot => Object.freeze({
-  ...snapshot,
-  root: redactNode(snapshot.root),
-  ...(snapshot.value === undefined ? {} : { value: redactJson(snapshot.value) }),
+export const noticeRedactionPlaceholder = (snapshot: AgentDocumentSnapshot): AgentDocumentSnapshot => Object.freeze({
+  root: Object.freeze({ kind: 'text' as const, text: NOTICE_REDACTION_MARK }),
+  status: snapshot.status,
+  version: snapshot.version,
 });
 
+const documentBytes = (document: AgentDocumentSnapshot): number =>
+  new TextEncoder().encode(JSON.stringify(document)).byteLength;
+
+/**
+ * Applies the secret pass to every free-text field of a detached snapshot.
+ * Structure, depth, node count, status, and codes are unchanged, so those
+ * bounds still hold; bytes need not — the mark is longer than the shortest
+ * values it replaces (`pass=abcd`, `a@b.co`), so a document authored at the
+ * byte bound can grow past it. A redacted document that no longer fits the
+ * bound the original passed is replaced by the placeholder rather than handed
+ * out oversized: the bound is a promise to hosts, made at publish and kept on
+ * egress.
+ */
+export const redactNoticeDocument = (snapshot: AgentDocumentSnapshot): AgentDocumentSnapshot => {
+  const redacted: AgentDocumentSnapshot = Object.freeze({
+    ...snapshot,
+    root: redactNode(snapshot.root),
+    ...(snapshot.value === undefined ? {} : { value: redactJson(snapshot.value) }),
+  });
+  return documentBytes(redacted) > DEFAULT_AGENT_RENDER_LIMITS.maxDocumentBytes
+    ? noticeRedactionPlaceholder(snapshot)
+    : redacted;
+};
+
 const firstProse = (node: AgentDocumentNode): string | undefined => {
   switch (node.kind) {
     case 'result':

packages/rsc-runtime/tests/notices-redaction.test.ts

@@ -14,6 +14,7 @@ import {
   createAgentNoticeLedger,
   createNoticeInboxSignaller,
   disclosedNoticeContent,
+  noticeRedactionPlaceholder,
   noticeTitle,
   redactNoticeDocument,
   redactSecretText,
@@ -27,8 +28,10 @@ import {
 } from '../src/notices/index.js';
 import type { AgentDocumentSnapshot } from '../src/index.js';
 import {
+  DEFAULT_AGENT_RENDER_LIMITS,
   agent,
   available,
+  createAgentDocument,
   runAgentRequest,
   unavailable,
 } from '../src/index.js';
@@ -206,6 +209,35 @@ describe('secret pass (flare-redact)', () => {
     expect((snapshot.root as { children: readonly { text?: string }[] }).children[0]!.text).toBe('password: p4ss');
   });
 
+  it('hands out the placeholder when redaction would grow a document past the byte bound', () => {
+    // 350,000 chars of six-character e-mails per node: each finding grows by
+    // four characters, so two nodes authored well inside 1 MiB redact to ~1.1 MiB.
+    const dense = 'x@y.io '.repeat(50_000);
+    const authored = createAgentDocument({
+      root: { children: [{ kind: 'text', text: dense }, { kind: 'text', text: dense }], kind: 'result' },
+      status: 'success',
+      version: 1,
+    });
+    expect(Buffer.byteLength(JSON.stringify(authored), 'utf8')).toBeLessThan(DEFAULT_AGENT_RENDER_LIMITS.maxDocumentBytes);
+    expect(redactNoticeDocument(authored)).toEqual(noticeRedactionPlaceholder(authored));
+    expect(redactNoticeDocument(authored)).toEqual({ root: { kind: 'text', text: NOTICE_REDACTION_MARK }, status: 'success', version: 1 });
+    // One node of the same text still fits and is redacted in place.
+    const single = createAgentDocument({ root: { kind: 'text', text: dense }, status: 'success', version: 1 });
+    expect((redactNoticeDocument(single).root as { text: string }).text).toBe(`${NOTICE_REDACTION_MARK} `.repeat(50_000));
+  });
+
+  it('fails closed to the mark when the library refuses to bound a string', () => {
+    // flare-redact throws RedactionLimitError past 50,000 findings in one string.
+    const pathological = 'x@y.io '.repeat(50_001);
+    expect(redactSecretText(pathological)).toBe(NOTICE_REDACTION_MARK);
+    expect(containsSecretText(pathological)).toBe(true);
+    expect(redactNoticeDocument({
+      root: { kind: 'json', value: { note: 'keep', wall: [pathological] } },
+      status: 'success',
+      version: 1,
+    }).root).toEqual({ kind: 'json', value: NOTICE_REDACTION_MARK });
+  });
+
   it('projects a bounded single-line title for title-only routes', () => {
     expect(noticeTitle(document('  \n First line here\nsecond'))).toBe('First line here');
     expect(noticeTitle(document('x'.repeat(200))).length).toBe(120);