dsh-boost 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1 +1 @@
1
- {"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/projection/apply.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Projection execution: the shadow accounting and the real replacement.\n *\n * `projectShadow` is the half of projection that never changes what the model\n * sees: it decides whether a receipt *would* be cut, composes the replacement\n * string `projectApply` would produce, and prices both sides in tokens through\n * the caller's `estimate`. It writes nothing and reads no host service, so the\n * caller alone decides which mode to invoke (design §5.4).\n *\n * `projectApply` is the half that replaces, and it only replaces what is still\n * recoverable: the canonical receipt is persisted through the injected spill\n * backend first, then head line, head, spill footer and tail are composed. All\n * guards run before the write, a failed write or footer is a skip rather than\n * an exception, and a footer that would grow the receipt sends the original\n * back unchanged — a projection that grows a receipt defeats the plugin's\n * premise.\n *\n * The projected size is composed here, not read off `Truncation.after`:\n * `after` is the head line plus the two windows *without* the omission note, so\n * it is only a lower bound on the final replacement. Shadow mode prices\n * `renderHeadLine + head + omission note + tail`; the note's locator part is\n * unknown before the spill write, so only the standardized omission clause is\n * included.\n *\n * Skip reasons are stable codes, never prose: `error-receipt` (an error receipt\n * is evidence and is never projected), `family-not-configured` (the family has\n * no window), `not-worth-it` (`truncate`'s guard said no, or the footer left no\n * net gain), `empty` (shadow's empty receipt), and on the apply half\n * `no-spill`, `no-owner`, `projection-skipped:no-footer`, `spill-failed`, and\n * `footer-failed`.\n *\n * @module dsh-boost/projection/apply\n */\nimport type { BoostConfig, ProjectionParams, ToolFamily } from '../types.js'\nimport { renderHeadLine, truncate } from './truncate.js'\nimport type { Truncation } from './truncate.js'\n\n/** Which projection behaviour the caller is running. */\nexport type ProjectionMode = 'off' | 'shadow' | 'on'\n\n/** What projection did, or would have done, to one receipt. */\nexport interface ProjectionOutcome {\n kind: 'skipped' | 'shadow' | 'applied'\n /** Stable skip code; present only when `kind === 'skipped'`. */\n reason?: string\n /**\n * Tokens in the original receipt.\n *\n * Present only when `kind === 'shadow'` and the estimator priced both\n * sides; absent (with `estimate: 'unknown'` on the receipt) when it did not.\n */\n before?: number\n /** Tokens in the replacement shadow mode would have produced. */\n after?: number\n /** `before - after`. */\n saved?: number\n /**\n * UTF-8 bytes the replacement omits; present only when `kind === 'applied'`.\n *\n * Apply mode has no token estimator: the caller (T23b) prices both texts\n * itself, and these two fields are the projection's own accounting.\n */\n omittedBytes?: number\n /** Unicode code points the replacement omits; applied outcomes only. */\n omittedCodePoints?: number\n /**\n * The persisted artifact's locator; applied outcomes only.\n *\n * It is the path the footer tells the model to read, and the retrieval ledger\n * matches later `read`/`grep` arguments against it (Task 25).\n */\n locator?: string\n}\n\n/** A persisted spill artifact's model-facing handle. */\nexport interface SpillHandle {\n /** Opaque locator the model can `read` or `grep`; never parsed here. */\n locator: string\n /** How to retrieve the artifact, as guidance for the model. */\n retrievalHint: string\n}\n\n/**\n * The host spill store, narrowed to the one method projection needs.\n *\n * `callId` and `label` are required because the host's `SaveTextSpill` requires\n * them; `projectApply` fills them in before calling. `saveText` rejects on a\n * real storage failure, and that rejection is handled as a skip.\n */\nexport interface SpillBackend {\n saveText(input: {\n owner: { sessionId: string }\n source: { kind: 'tool'; toolName: string; callId: string; label: string }\n suggestedName: string\n content: string\n }): Promise<SpillHandle>\n}\n\n/**\n * Render the footer that names what was omitted and where the original lives.\n *\n * Injected by the caller, which dynamically imports the host's\n * `formatSpillNotice`; this module must never statically import\n * `@deepseek-ai/dsh-spill-policy` — it is not declared as a dependency, and a static import\n * would make the degradation path unreachable (design §5.4).\n */\nexport type FormatFooter = (omitted: { kind: 'exact'; count: number }, ref: SpillHandle) => string\n\n/** Everything one apply decision reads; every host service arrives pre-bound. */\nexport interface ProjectApplyInput {\n /** Canonical receipt text, byte for byte as it would enter history. */\n text: string\n /** Whether the host marked the receipt as an error. */\n isError: boolean\n /** Projection family, which selects the window from `cfg`. */\n family: ToolFamily\n /** Resolved plugin configuration. */\n cfg: BoostConfig\n /** Owning session; without one the spill has no owner and projection stops. */\n sessionId: string | undefined\n /** Tool name, recorded on the spill source and used for its file name. */\n toolName: string\n /** Model-issued call id; defaults to `toolName`. */\n callId?: string\n /** Human label for the artifact; defaults to `family`. */\n label?: string\n /** Spill backend, absent when the host has none (projection then stops). */\n spill: SpillBackend | undefined\n /** Footer renderer, absent when the host spill policy package is not installed. */\n formatFooter: FormatFooter | undefined\n}\n\n/** The omission clause of the spill footer; the locator is unknown here. */\nfunction omissionNote(omittedBytes: number): string {\n return `(Omitted ${omittedBytes} bytes.)`\n}\n\n/**\n * The replacement shadow mode prices: head line, head, omission note, tail.\n *\n * `projectApply` replaces the note with the persisted spill footer; because the\n * locator text is not known before that write, this is a lower bound.\n */\nfunction projectedText(truncation: Truncation): string {\n return `${renderHeadLine(truncation)}\\n${truncation.head}\\n${omissionNote(truncation.omittedBytes)}\\n${truncation.tail}`\n}\n\n/** Price the original and the replacement together, so the pair always agrees. */\nfunction measure(\n original: string,\n replacement: string,\n estimate: (s: string) => number,\n): Pick<ProjectionOutcome, 'before' | 'after' | 'saved'> | undefined {\n const before = estimate(original)\n const after = estimate(replacement)\n // A non-finite estimate is an unknown, never a number to serialise: JSON\n // would turn NaN into `null`, which looks like a measured zero in the\n // shadow account. The caller writes `estimate: 'unknown'` instead.\n if (!Number.isFinite(before) || !Number.isFinite(after)) return undefined\n return { before, after, saved: before - after }\n}\n\n/**\n * Report what projection would save, without touching the receipt.\n *\n * Guards run in a fixed order: an error receipt is skipped before anything\n * else, so even an empty or oversized error keeps its evidence (design §5.4\n * contract 4); then empty text; then a family with no configured window; then\n * `truncate`'s own decision (trigger, 256 KiB cap, net-gain guard).\n */\nexport async function projectShadow(input: {\n /** Canonical receipt text, byte for byte as it would enter history. */\n text: string\n /** Whether the host marked the receipt as an error. */\n isError: boolean\n /** Projection family, which selects the window from `cfg`. */\n family: ToolFamily\n /** Resolved plugin configuration. */\n cfg: BoostConfig\n /** Token estimator injected by the caller (never imported from the host). */\n estimate: (s: string) => number\n}): Promise<ProjectionOutcome> {\n const { text, isError, family, cfg, estimate } = input\n\n if (isError) return { kind: 'skipped', reason: 'error-receipt' }\n if (text === '') return { kind: 'skipped', reason: 'empty' }\n\n const params: ProjectionParams | undefined = cfg.projection[family]\n if (!params) return { kind: 'skipped', reason: 'family-not-configured' }\n\n const truncation = truncate(text, params)\n if (truncation === null) return { kind: 'skipped', reason: 'not-worth-it' }\n\n const measured = measure(text, projectedText(truncation), estimate)\n return measured === undefined ? { kind: 'shadow' } : { kind: 'shadow', ...measured }\n}\n\n/** The prechecks that passed, with the host pieces narrowed to their present values. */\ninterface Ready {\n truncation: Truncation\n owner: { sessionId: string }\n spill: SpillBackend\n formatFooter: FormatFooter\n}\n\n/**\n * Decide whether the receipt may be replaced, in the plan's fixed order.\n *\n * Every guard returns the intact receipt and a stable code: an error receipt\n * first (it is evidence, design §5.4 contract 4); then a family with no window;\n * then `truncate`'s decision — calling it once is the same decision\n * `shouldTruncate` exposes, without cutting twice; then the host pieces that\n * would make the footer a lie: no backend, no owner, no footer renderer. None\n * of these writes anything.\n */\nfunction precheck(input: ProjectApplyInput): { skip: ProjectionOutcome } | Ready {\n const { text, isError, family, cfg, sessionId, spill, formatFooter } = input\n\n if (isError) return { skip: { kind: 'skipped', reason: 'error-receipt' } }\n\n const params: ProjectionParams | undefined = cfg.projection[family]\n if (!params) return { skip: { kind: 'skipped', reason: 'family-not-configured' } }\n\n const truncation = truncate(text, params)\n if (truncation === null) return { skip: { kind: 'skipped', reason: 'not-worth-it' } }\n\n if (!spill) return { skip: { kind: 'skipped', reason: 'no-spill' } }\n if (!sessionId) return { skip: { kind: 'skipped', reason: 'no-owner' } }\n if (!formatFooter) return { skip: { kind: 'skipped', reason: 'projection-skipped:no-footer' } }\n\n return { truncation, owner: { sessionId }, spill, formatFooter }\n}\n\n/**\n * Replace an oversized receipt with its head, tail, and a way back to the rest.\n *\n * The canonical original is spilled *before* anything is replaced — never the\n * projection, which would make the footer point at an artifact that does not\n * contain what it promises. The footer sits on its own line between the two\n * windows, and the composed replacement is re-checked against the original:\n * at the trigger boundary a long locator can make the \"projection\" longer than\n * the receipt it replaces, and a projection that grows a receipt is worse than\n * none.\n *\n * A spill or footer failure is swallowed and reported as `spill-failed` /\n * `footer-failed`; the caller's `post-execute` hook must never see an exception\n * from here. The footer must be guarded too: the host turns a throwing\n * `post-execute` listener into an `isError` result, which would lose the very\n * output this module exists to preserve.\n */\nexport async function projectApply(\n input: ProjectApplyInput,\n): Promise<{ content: string; outcome: ProjectionOutcome }> {\n const ready = precheck(input)\n if ('skip' in ready) return { content: input.text, outcome: ready.skip }\n\n const { text, family, toolName, callId, label } = input\n const { truncation, owner, spill, formatFooter } = ready\n\n // One guard covers both host calls: `saveText` and the footer renderer. The\n // marker tells the two failures apart, because status counts distinguish\n // them — and neither may reach the caller as an exception.\n let phase: 'spill' | 'footer' = 'spill'\n try {\n const ref = await spill.saveText({\n owner,\n source: { kind: 'tool', toolName, callId: callId ?? toolName, label: label ?? family },\n suggestedName: `${toolName}.txt`,\n content: text,\n })\n phase = 'footer'\n\n const footer = formatFooter({ kind: 'exact', count: truncation.omittedBytes }, ref)\n const assembled = `${renderHeadLine(truncation)}\\n${truncation.head}\\n${footer}\\n${truncation.tail}`\n\n // The footer is only known after the write, so this check can only run now.\n // The backend exposes no delete: a spill that reaches this point stays in\n // the store, unreferenced, while the model gets the original content back.\n if (assembled.length >= text.length) {\n return { content: text, outcome: { kind: 'skipped', reason: 'not-worth-it' } }\n }\n\n return {\n content: assembled,\n outcome: {\n kind: 'applied',\n omittedBytes: truncation.omittedBytes,\n omittedCodePoints: truncation.omittedCodePoints,\n locator: ref.locator,\n },\n }\n } catch {\n return {\n content: text,\n outcome: { kind: 'skipped', reason: phase === 'spill' ? 'spill-failed' : 'footer-failed' },\n }\n }\n}\n"]}
1
+ {"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/projection/apply.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Projection execution: the shadow accounting and the real replacement.\n *\n * `projectShadow` is the half of projection that never changes what the model\n * sees: it decides whether a receipt *would* be cut, composes the replacement\n * string `projectApply` would produce, and prices both sides in tokens through\n * the caller's `estimate`. It writes nothing and reads no host service, so the\n * caller alone decides which mode to invoke (design §5.4).\n *\n * `projectApply` is the half that replaces, and it only replaces what is still\n * recoverable: the canonical receipt is persisted through the injected spill\n * backend first, then head line, head, spill footer and tail are composed. All\n * guards run before the write, a failed write or footer is a skip rather than\n * an exception, and a footer that would grow the receipt sends the original\n * back unchanged — a projection that grows a receipt defeats the plugin's\n * premise.\n *\n * The projected size is composed here, not read off `Truncation.after`:\n * `after` is the head line plus the two windows *without* the omission note, so\n * it is only a lower bound on the final replacement. Shadow mode prices\n * `renderHeadLine + head + omission note + tail`; the note's locator part is\n * unknown before the spill write, so only the standardized omission clause is\n * included.\n *\n * Skip reasons are stable codes, never prose: `error-receipt` (an error receipt\n * is evidence and is never projected), `family-not-configured` (the family has\n * no window), `not-worth-it` (`truncate`'s guard said no, or the footer left no\n * net gain), `empty` (shadow's empty receipt), and on the apply half\n * `no-spill`, `no-owner`, `projection-skipped:no-footer`, `spill-failed`, and\n * `footer-failed`.\n *\n * @module dsh-boost/projection/apply\n */\nimport type { BoostConfig, ProjectionParams, ToolFamily } from '../types.js'\nimport { renderHeadLine, truncate } from './truncate.js'\nimport type { Truncation } from './truncate.js'\n\n/** Which projection behaviour the caller is running. */\nexport type ProjectionMode = 'off' | 'shadow' | 'on'\n\n/** What projection did, or would have done, to one receipt. */\nexport interface ProjectionOutcome {\n kind: 'skipped' | 'shadow' | 'applied'\n /** Stable skip code; present only when `kind === 'skipped'`. */\n reason?: string\n /**\n * Tokens in the original receipt.\n *\n * Present only when `kind === 'shadow'` and the estimator priced both\n * sides; absent (with `estimate: 'unknown'` on the receipt) when it did not.\n */\n before?: number\n /** Tokens in the replacement shadow mode would have produced. */\n after?: number\n /** `before - after`. */\n saved?: number\n /**\n * UTF-8 bytes the replacement omits; present only when `kind === 'applied'`.\n *\n * Apply mode has no token estimator: the caller (T23b) prices both texts\n * itself, and these two fields are the projection's own accounting.\n */\n omittedBytes?: number\n /** Unicode code points the replacement omits; applied outcomes only. */\n omittedCodePoints?: number\n /**\n * The persisted artifact's locator; applied outcomes only.\n *\n * It is the path the footer tells the model to read, and the retrieval ledger\n * matches later `read`/`grep` arguments against it (Task 25).\n */\n locator?: string\n}\n\n/** A persisted spill artifact's model-facing handle. */\nexport interface SpillHandle {\n /** Opaque locator the model can `read` or `grep`; never parsed here. */\n locator: string\n /** How to retrieve the artifact, as guidance for the model. */\n retrievalHint: string\n}\n\n/**\n * The host spill store, narrowed to the one method projection needs.\n *\n * `callId` and `label` are required because the host's `SaveTextSpill` requires\n * them; `projectApply` fills them in before calling. `saveText` rejects on a\n * real storage failure, and that rejection is handled as a skip.\n */\nexport interface SpillBackend {\n saveText(input: {\n owner: { sessionId: string }\n source: { kind: 'tool'; toolName: string; callId: string; label: string }\n suggestedName: string\n content: string\n }): Promise<SpillHandle>\n}\n\n/**\n * Render the footer that names what was omitted and where the original lives.\n *\n * Injected by the caller, which dynamically imports the host's\n * `formatSpillNotice`; this module must never statically import\n * `@deepseek-ai/dsh-spill-policy` — it is not declared as a dependency, and a static import\n * would make the degradation path unreachable (design §5.4).\n */\nexport type FormatFooter = (omitted: { kind: 'exact'; count: number }, ref: SpillHandle) => string\n\n/** Everything one apply decision reads; every host service arrives pre-bound. */\nexport interface ProjectApplyInput {\n /** Canonical receipt text, byte for byte as it would enter history. */\n text: string\n /** Whether the host marked the receipt as an error. */\n isError: boolean\n /** Projection family, which selects the window from `cfg`. */\n family: ToolFamily\n /** Resolved plugin configuration. */\n cfg: BoostConfig\n /** Owning session; without one the spill has no owner and projection stops. */\n sessionId: string | undefined\n /** Tool name, recorded on the spill source and used for its file name. */\n toolName: string\n /** Model-issued call id; defaults to `toolName`. */\n callId?: string\n /** Human label for the artifact; defaults to `family`. */\n label?: string\n /** Spill backend, absent when the host has none (projection then stops). */\n spill: SpillBackend | undefined\n /** Footer renderer, absent when the host spill policy package is not installed. */\n formatFooter: FormatFooter | undefined\n}\n\n/** The omission clause of the spill footer; the locator is unknown here. */\nfunction omissionNote(omittedBytes: number): string {\n return `(Omitted ${omittedBytes} bytes.)`\n}\n\n/**\n * The replacement shadow mode prices: head line, head, omission note, tail.\n *\n * `projectApply` replaces the note with the persisted spill footer; because the\n * locator text is not known before that write, this is a lower bound.\n */\nfunction projectedText(truncation: Truncation): string {\n return `${renderHeadLine(truncation)}\\n${truncation.head}\\n${omissionNote(truncation.omittedBytes)}\\n${truncation.tail}${signalSuffix(truncation)}`\n}\n\n/**\n * The marker lines `truncate` rescued from the cut-away middle, appended after\n * the tail so the model still sees an exit code or error flag that would\n * otherwise be lost (design §5.4-4). Empty for the overwhelming majority.\n */\nfunction signalSuffix(truncation: Truncation): string {\n const signals = truncation.signals ?? []\n return signals.length === 0 ? '' : `\\n${signals.join('\\n')}`\n}\n\n/** Price the original and the replacement together, so the pair always agrees. */\nfunction measure(\n original: string,\n replacement: string,\n estimate: (s: string) => number,\n): Pick<ProjectionOutcome, 'before' | 'after' | 'saved'> | undefined {\n const before = estimate(original)\n const after = estimate(replacement)\n // A non-finite estimate is an unknown, never a number to serialise: JSON\n // would turn NaN into `null`, which looks like a measured zero in the\n // shadow account. The caller writes `estimate: 'unknown'` instead.\n if (!Number.isFinite(before) || !Number.isFinite(after)) return undefined\n return { before, after, saved: before - after }\n}\n\n/**\n * Report what projection would save, without touching the receipt.\n *\n * Guards run in a fixed order: an error receipt is skipped before anything\n * else, so even an empty or oversized error keeps its evidence (design §5.4\n * contract 4); then empty text; then a family with no configured window; then\n * `truncate`'s own decision (trigger, 256 KiB cap, net-gain guard).\n */\nexport async function projectShadow(input: {\n /** Canonical receipt text, byte for byte as it would enter history. */\n text: string\n /** Whether the host marked the receipt as an error. */\n isError: boolean\n /** Projection family, which selects the window from `cfg`. */\n family: ToolFamily\n /** Resolved plugin configuration. */\n cfg: BoostConfig\n /** Token estimator injected by the caller (never imported from the host). */\n estimate: (s: string) => number\n}): Promise<ProjectionOutcome> {\n const { text, isError, family, cfg, estimate } = input\n\n if (isError) return { kind: 'skipped', reason: 'error-receipt' }\n if (text === '') return { kind: 'skipped', reason: 'empty' }\n\n const params: ProjectionParams | undefined = cfg.projection[family]\n if (!params) return { kind: 'skipped', reason: 'family-not-configured' }\n\n const truncation = truncate(text, params)\n if (truncation === null) return { kind: 'skipped', reason: 'not-worth-it' }\n\n const measured = measure(text, projectedText(truncation), estimate)\n return measured === undefined ? { kind: 'shadow' } : { kind: 'shadow', ...measured }\n}\n\n/** The prechecks that passed, with the host pieces narrowed to their present values. */\ninterface Ready {\n truncation: Truncation\n owner: { sessionId: string }\n spill: SpillBackend\n formatFooter: FormatFooter\n}\n\n/**\n * Decide whether the receipt may be replaced, in the plan's fixed order.\n *\n * Every guard returns the intact receipt and a stable code: an error receipt\n * first (it is evidence, design §5.4 contract 4); then a family with no window;\n * then `truncate`'s decision — calling it once is the same decision\n * `shouldTruncate` exposes, without cutting twice; then the host pieces that\n * would make the footer a lie: no backend, no owner, no footer renderer. None\n * of these writes anything.\n */\nfunction precheck(input: ProjectApplyInput): { skip: ProjectionOutcome } | Ready {\n const { text, isError, family, cfg, sessionId, spill, formatFooter } = input\n\n if (isError) return { skip: { kind: 'skipped', reason: 'error-receipt' } }\n\n const params: ProjectionParams | undefined = cfg.projection[family]\n if (!params) return { skip: { kind: 'skipped', reason: 'family-not-configured' } }\n\n const truncation = truncate(text, params)\n if (truncation === null) return { skip: { kind: 'skipped', reason: 'not-worth-it' } }\n\n if (!spill) return { skip: { kind: 'skipped', reason: 'no-spill' } }\n if (!sessionId) return { skip: { kind: 'skipped', reason: 'no-owner' } }\n if (!formatFooter) return { skip: { kind: 'skipped', reason: 'projection-skipped:no-footer' } }\n\n return { truncation, owner: { sessionId }, spill, formatFooter }\n}\n\n/**\n * Replace an oversized receipt with its head, tail, and a way back to the rest.\n *\n * The canonical original is spilled *before* anything is replaced — never the\n * projection, which would make the footer point at an artifact that does not\n * contain what it promises. The footer sits on its own line between the two\n * windows, and the composed replacement is re-checked against the original:\n * at the trigger boundary a long locator can make the \"projection\" longer than\n * the receipt it replaces, and a projection that grows a receipt is worse than\n * none.\n *\n * A spill or footer failure is swallowed and reported as `spill-failed` /\n * `footer-failed`; the caller's `post-execute` hook must never see an exception\n * from here. The footer must be guarded too: the host turns a throwing\n * `post-execute` listener into an `isError` result, which would lose the very\n * output this module exists to preserve.\n */\nexport async function projectApply(\n input: ProjectApplyInput,\n): Promise<{ content: string; outcome: ProjectionOutcome }> {\n const ready = precheck(input)\n if ('skip' in ready) return { content: input.text, outcome: ready.skip }\n\n const { text, family, toolName, callId, label } = input\n const { truncation, owner, spill, formatFooter } = ready\n\n // One guard covers both host calls: `saveText` and the footer renderer. The\n // marker tells the two failures apart, because status counts distinguish\n // them — and neither may reach the caller as an exception.\n let phase: 'spill' | 'footer' = 'spill'\n try {\n const ref = await spill.saveText({\n owner,\n source: { kind: 'tool', toolName, callId: callId ?? toolName, label: label ?? family },\n suggestedName: `${toolName}.txt`,\n content: text,\n })\n phase = 'footer'\n\n const footer = formatFooter({ kind: 'exact', count: truncation.omittedBytes }, ref)\n const assembled = `${renderHeadLine(truncation)}\\n${truncation.head}\\n${footer}\\n${truncation.tail}${signalSuffix(truncation)}`\n\n // The footer is only known after the write, so this check can only run now.\n // The backend exposes no delete: a spill that reaches this point stays in\n // the store, unreferenced, while the model gets the original content back.\n if (assembled.length >= text.length) {\n return { content: text, outcome: { kind: 'skipped', reason: 'not-worth-it' } }\n }\n\n return {\n content: assembled,\n outcome: {\n kind: 'applied',\n omittedBytes: truncation.omittedBytes,\n omittedCodePoints: truncation.omittedCodePoints,\n locator: ref.locator,\n },\n }\n } catch {\n return {\n content: text,\n outcome: { kind: 'skipped', reason: phase === 'spill' ? 'spill-failed' : 'footer-failed' },\n }\n }\n}\n"]}
@@ -8,16 +8,27 @@ export function renderHeadLine(truncation) {
8
8
  function headLine(outputChars, firstChars, lastChars) {
9
9
  return `[output ${outputChars.toLocaleString('en-US')} chars; showing first ${firstChars.toLocaleString('en-US')} and last ${lastChars.toLocaleString('en-US')}]`;
10
10
  }
11
+ /** The marker lines the design's §5.4-4 says must survive any projection. */
12
+ const PRESERVED_SIGNAL = /^(?:\[exit code: -?\d+\]|exit_code\s*[:=]\s*-?\d+|is_error\s*[:=]\s*(?:true|false))$/i;
11
13
  /**
12
- * Whether `truncate` would cut `text`.
13
- *
14
- * Delegates instead of re-deriving the decision, so the two entry points can
15
- * never disagree at the edges (the exact cut, the net-gain guard, the byte
16
- * cap). The cheap pre-filters inside `truncate` keep the common "not worth
17
- * cutting" path free of code-point allocation.
14
+ * Marker lines from the omitted middle, capped so a pathological receipt cannot
15
+ * make the projection longer than what it replaced.
18
16
  */
19
- export function shouldTruncate(text, params) {
20
- return truncate(text, params) !== null;
17
+ function preservedSignals(middle) {
18
+ if (middle.length === 0)
19
+ return [];
20
+ const out = [];
21
+ for (const line of middle.join('').split('\n')) {
22
+ const trimmed = line.trim();
23
+ if (trimmed === '' || !PRESERVED_SIGNAL.test(trimmed))
24
+ continue;
25
+ if (out.includes(trimmed))
26
+ continue;
27
+ out.push(trimmed);
28
+ if (out.length === 8)
29
+ break;
30
+ }
31
+ return out;
21
32
  }
22
33
  /** Cut `text` down to its head and tail windows, or `null` when that is not worth it. */
23
34
  export function truncate(text, params) {
@@ -42,16 +53,22 @@ export function truncate(text, params) {
42
53
  const tail = params.tailChars === 0 ? '' : codePoints.slice(-params.tailChars).join('');
43
54
  const omittedCodePoints = codePoints.length - params.headChars - params.tailChars;
44
55
  const omittedBytes = beforeBytes - Buffer.byteLength(head, 'utf8') - Buffer.byteLength(tail, 'utf8');
56
+ // Signals a reader must never lose, even when they sit in the middle that the
57
+ // two windows cut away: an error flag, an exit code, the `[exit code: N]`
58
+ // suffix the tool executor appends (design §5.4-4). They are re-emitted after
59
+ // the tail so the projection stays append-only from the reader's view.
60
+ const preserved = preservedSignals(codePoints.slice(params.headChars, codePoints.length - params.tailChars));
45
61
  // The replacement this layer can render: the head line plus the two windows.
46
62
  // The apply stage inserts the spill footer between the windows; that footer is
47
63
  // not known here, so this is a lower bound on the final projected length.
48
64
  const header = headLine(codePoints.length, Array.from(head).length, Array.from(tail).length);
49
- const after = `${header}\n${head}\n${tail}`;
65
+ const signals = preserved.length === 0 ? '' : `\n${preserved.join('\n')}`;
66
+ const after = `${header}\n${head}\n${tail}${signals}`;
50
67
  // A cut that would not shrink the receipt (misconfigured windows, or windows
51
68
  // that together swallow the whole text) is not worth taking; fall back to the
52
69
  // original rather than throwing on unvalidated config.
53
70
  if (after.length >= text.length)
54
71
  return null;
55
- return { before: text, after, head, tail, omittedBytes, omittedCodePoints };
72
+ return { before: text, after, head, tail, omittedBytes, omittedCodePoints, signals: preserved };
56
73
  }
57
74
  //# sourceMappingURL=truncate.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../src/projection/truncate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Receipt truncation: whether to cut, the two windows, and the head line.\n *\n * Lengths are counted in Unicode code points, never UTF-16 code units (design\n * §5.4): a CJK or emoji receipt must be cut at the same visual length as an\n * ASCII one, and slicing the code-point array is the only way never to split a\n * surrogate pair. `text.length` appears only as a cheap pre-filter — it is an\n * upper bound on the code-point count, so `text.length <= triggerChars` proves\n * that no cut is due.\n *\n * `truncate` returns `null` when a cut is not worth it: when the receipt does\n * not exceed the trigger, when its UTF-8 size exceeds the projection cap, or\n * when the rendered replacement would not be shorter than the original. Every\n * non-null result therefore satisfies `after.length < before.length`, which\n * the shadow-mode accounting relies on.\n *\n * @module dsh-boost/projection/truncate\n */\nimport type { ProjectionParams } from '../types.js'\n\n/** Receipts above this many UTF-8 bytes are never projected (design §5.4). */\nconst MAX_PROJECTED_BYTES = 256 * 1024\n\n/** The two windows plus the facts later stages report and account for. */\nexport interface Truncation {\n /** The original receipt text, byte for byte. */\n before: string\n /** The rendered replacement: head line, then head, then tail. */\n after: string\n /** First `headChars` code points of `before`. */\n head: string\n /** Last `tailChars` code points of `before`. */\n tail: string\n /** UTF-8 bytes of `before` that neither window carries. */\n omittedBytes: number\n /** `before` code points minus the two window sizes. */\n omittedCodePoints: number\n}\n\n/** Render the head line of a truncation, with `en-US` thousands separators. */\nexport function renderHeadLine(truncation: Truncation): string {\n return headLine(\n Array.from(truncation.before).length,\n Array.from(truncation.head).length,\n Array.from(truncation.tail).length,\n )\n}\n\n/** The one place the head line's literal format lives. */\nfunction headLine(outputChars: number, firstChars: number, lastChars: number): string {\n return `[output ${outputChars.toLocaleString('en-US')} chars; showing first ${firstChars.toLocaleString('en-US')} and last ${lastChars.toLocaleString('en-US')}]`\n}\n\n/**\n * Whether `truncate` would cut `text`.\n *\n * Delegates instead of re-deriving the decision, so the two entry points can\n * never disagree at the edges (the exact cut, the net-gain guard, the byte\n * cap). The cheap pre-filters inside `truncate` keep the common \"not worth\n * cutting\" path free of code-point allocation.\n */\nexport function shouldTruncate(text: string, params: ProjectionParams): boolean {\n return truncate(text, params) !== null\n}\n\n/** Cut `text` down to its head and tail windows, or `null` when that is not worth it. */\nexport function truncate(text: string, params: ProjectionParams): Truncation | null {\n // UTF-16 length upper-bounds the code-point count: when it does not exceed\n // the trigger, neither can the real count.\n if (text.length <= params.triggerChars) return null\n\n // Large receipts are not projected at all. The design's 256 KiB is a byte\n // budget, so measure UTF-8 bytes rather than UTF-16 units — otherwise CJK\n // and emoji receipts would overflow the budget by 2–4×.\n const beforeBytes = Buffer.byteLength(text, 'utf8')\n if (beforeBytes > MAX_PROJECTED_BYTES) return null\n\n const codePoints = Array.from(text)\n if (codePoints.length <= params.triggerChars) return null\n\n // Slicing the code-point array cannot split a surrogate pair; string\n // indexing could.\n const head = codePoints.slice(0, params.headChars).join('')\n // `slice(-0)` is `slice(0)`, i.e. the whole text: a configured zero tail must\n // be no tail, not a duplicate of the receipt (review row 69).\n const tail = params.tailChars === 0 ? '' : codePoints.slice(-params.tailChars).join('')\n const omittedCodePoints = codePoints.length - params.headChars - params.tailChars\n const omittedBytes = beforeBytes - Buffer.byteLength(head, 'utf8') - Buffer.byteLength(tail, 'utf8')\n\n // The replacement this layer can render: the head line plus the two windows.\n // The apply stage inserts the spill footer between the windows; that footer is\n // not known here, so this is a lower bound on the final projected length.\n const header = headLine(codePoints.length, Array.from(head).length, Array.from(tail).length)\n const after = `${header}\\n${head}\\n${tail}`\n // A cut that would not shrink the receipt (misconfigured windows, or windows\n // that together swallow the whole text) is not worth taking; fall back to the\n // original rather than throwing on unvalidated config.\n if (after.length >= text.length) return null\n\n return { before: text, after, head, tail, omittedBytes, omittedCodePoints }\n}\n"]}
1
+ {"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../src/projection/truncate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Receipt truncation: whether to cut, the two windows, and the head line.\n *\n * Lengths are counted in Unicode code points, never UTF-16 code units (design\n * §5.4): a CJK or emoji receipt must be cut at the same visual length as an\n * ASCII one, and slicing the code-point array is the only way never to split a\n * surrogate pair. `text.length` appears only as a cheap pre-filter — it is an\n * upper bound on the code-point count, so `text.length <= triggerChars` proves\n * that no cut is due.\n *\n * `truncate` returns `null` when a cut is not worth it: when the receipt does\n * not exceed the trigger, when its UTF-8 size exceeds the projection cap, or\n * when the rendered replacement would not be shorter than the original. Every\n * non-null result therefore satisfies `after.length < before.length`, which\n * the shadow-mode accounting relies on.\n *\n * @module dsh-boost/projection/truncate\n */\nimport type { ProjectionParams } from '../types.js'\n\n/** Receipts above this many UTF-8 bytes are never projected (design §5.4). */\nconst MAX_PROJECTED_BYTES = 256 * 1024\n\n/** The two windows plus the facts later stages report and account for. */\nexport interface Truncation {\n /** The original receipt text, byte for byte. */\n before: string\n /** The rendered replacement: head line, then head, then tail. */\n after: string\n /** First `headChars` code points of `before`. */\n head: string\n /** Last `tailChars` code points of `before`. */\n tail: string\n /** UTF-8 bytes of `before` that neither window carries. */\n omittedBytes: number\n /** `before` code points minus the two window sizes. */\n omittedCodePoints: number\n /**\n * Marker lines from the cut-away middle that must survive (design §5.4-4):\n * an exit code or error flag the reader would otherwise lose. Empty for the\n * overwhelming majority of receipts.\n */\n signals: string[]\n}\n\n/** Render the head line of a truncation, with `en-US` thousands separators. */\nexport function renderHeadLine(truncation: Truncation): string {\n return headLine(\n Array.from(truncation.before).length,\n Array.from(truncation.head).length,\n Array.from(truncation.tail).length,\n )\n}\n\n/** The one place the head line's literal format lives. */\nfunction headLine(outputChars: number, firstChars: number, lastChars: number): string {\n return `[output ${outputChars.toLocaleString('en-US')} chars; showing first ${firstChars.toLocaleString('en-US')} and last ${lastChars.toLocaleString('en-US')}]`\n}\n\n/** The marker lines the design's §5.4-4 says must survive any projection. */\nconst PRESERVED_SIGNAL = /^(?:\\[exit code: -?\\d+\\]|exit_code\\s*[:=]\\s*-?\\d+|is_error\\s*[:=]\\s*(?:true|false))$/i\n\n/**\n * Marker lines from the omitted middle, capped so a pathological receipt cannot\n * make the projection longer than what it replaced.\n */\nfunction preservedSignals(middle: readonly string[]): string[] {\n if (middle.length === 0) return []\n const out: string[] = []\n for (const line of middle.join('').split('\\n')) {\n const trimmed = line.trim()\n if (trimmed === '' || !PRESERVED_SIGNAL.test(trimmed)) continue\n if (out.includes(trimmed)) continue\n out.push(trimmed)\n if (out.length === 8) break\n }\n return out\n}\n\n/** Cut `text` down to its head and tail windows, or `null` when that is not worth it. */\nexport function truncate(text: string, params: ProjectionParams): Truncation | null {\n // UTF-16 length upper-bounds the code-point count: when it does not exceed\n // the trigger, neither can the real count.\n if (text.length <= params.triggerChars) return null\n\n // Large receipts are not projected at all. The design's 256 KiB is a byte\n // budget, so measure UTF-8 bytes rather than UTF-16 units — otherwise CJK\n // and emoji receipts would overflow the budget by 2–4×.\n const beforeBytes = Buffer.byteLength(text, 'utf8')\n if (beforeBytes > MAX_PROJECTED_BYTES) return null\n\n const codePoints = Array.from(text)\n if (codePoints.length <= params.triggerChars) return null\n\n // Slicing the code-point array cannot split a surrogate pair; string\n // indexing could.\n const head = codePoints.slice(0, params.headChars).join('')\n // `slice(-0)` is `slice(0)`, i.e. the whole text: a configured zero tail must\n // be no tail, not a duplicate of the receipt (review row 69).\n const tail = params.tailChars === 0 ? '' : codePoints.slice(-params.tailChars).join('')\n const omittedCodePoints = codePoints.length - params.headChars - params.tailChars\n const omittedBytes = beforeBytes - Buffer.byteLength(head, 'utf8') - Buffer.byteLength(tail, 'utf8')\n\n // Signals a reader must never lose, even when they sit in the middle that the\n // two windows cut away: an error flag, an exit code, the `[exit code: N]`\n // suffix the tool executor appends (design §5.4-4). They are re-emitted after\n // the tail so the projection stays append-only from the reader's view.\n const preserved = preservedSignals(codePoints.slice(params.headChars, codePoints.length - params.tailChars))\n\n // The replacement this layer can render: the head line plus the two windows.\n // The apply stage inserts the spill footer between the windows; that footer is\n // not known here, so this is a lower bound on the final projected length.\n const header = headLine(codePoints.length, Array.from(head).length, Array.from(tail).length)\n const signals = preserved.length === 0 ? '' : `\\n${preserved.join('\\n')}`\n const after = `${header}\\n${head}\\n${tail}${signals}`\n // A cut that would not shrink the receipt (misconfigured windows, or windows\n // that together swallow the whole text) is not worth taking; fall back to the\n // original rather than throwing on unvalidated config.\n if (after.length >= text.length) return null\n\n return { before: text, after, head, tail, omittedBytes, omittedCodePoints, signals: preserved }\n}\n"]}
@@ -49,6 +49,39 @@ const ERR_HOST_NO_TOKENMETER = 'ERR_HOST_NO_TOKENMETER';
49
49
  const ERR_HOST_NO_ESTIMATOR = 'ERR_HOST_NO_ESTIMATOR';
50
50
  const ERR_HOST_PLATFORM_UNSUPPORTED = 'ERR_HOST_PLATFORM_UNSUPPORTED';
51
51
  const ERR_HOST_NO_WORKSPACE_REGISTRY = 'ERR_HOST_NO_WORKSPACE_REGISTRY';
52
+ /**
53
+ * Stable degradation code: a workspace registry is present but cannot list.
54
+ *
55
+ * Presence alone made a throwing `list()` look healthy: the resolver swallowed
56
+ * the throw per call (the intentional fail-closed path for one invisible
57
+ * session), every session was judged invisible, and `status` reported a healthy
58
+ * plugin doing nothing (review row 6). The probe calls `list()` at status time,
59
+ * exactly as the token meter is probed, so a broken registry is named instead
60
+ * of being indistinguishable from an absent one.
61
+ */
62
+ const ERR_HOST_WORKSPACE_REGISTRY_BROKEN = 'ERR_HOST_WORKSPACE_REGISTRY_BROKEN';
63
+ /**
64
+ * Stable degradation code: `spillStore` is present but exposes no `saveText`.
65
+ *
66
+ * `hasSpill` was presence-only, so a `{}` service reported a healthy spill path
67
+ * until the first projection failed (review row 50). The store is probed at
68
+ * status time for the one method the projection path calls; the notice module
69
+ * stays covered by `ERR_HOST_NO_SPILL_NOTICE` / `projection-skipped:no-footer`,
70
+ * because it is reached by `import()` and has no service to probe.
71
+ */
72
+ const ERR_HOST_SPILL_UNUSABLE = 'ERR_HOST_SPILL_UNUSABLE';
73
+ /**
74
+ * Stable degradation code: multi-candidate plans will abstain.
75
+ *
76
+ * The selector is the only consumer of the host LLM. Its absence or a failing
77
+ * call is written as `selector-unavailable` / `selector-error`, but those are
78
+ * receipt counts: an operator reading `degraded` saw a healthy plugin while
79
+ * every multi-candidate plan abstained (review row 49). Single-candidate
80
+ * substitution still works, so this is a warning, not a failure. A
81
+ * `selector-abstain` is deliberately not mapped: the model declined an
82
+ * ambiguous plan, which is not a host capability absence.
83
+ */
84
+ const ERR_HOST_SELECTOR_UNAVAILABLE = 'ERR_HOST_SELECTOR_UNAVAILABLE';
52
85
  /**
53
86
  * Stable degradation code: at least one receipt shard could not be read.
54
87
  *
@@ -104,6 +137,12 @@ const ERR_HOST_COMPLETE_SECTION = 'ERR_HOST_COMPLETE_SECTION';
104
137
  * failing sends them to the wrong place. `footer-failed` stays with
105
138
  * `ERR_HOST_NO_SPILL_NOTICE` because both mean the same thing at the point of
106
139
  * use — the footer cannot be produced.
140
+ *
141
+ * `selector-unavailable` and `selector-error` are the selector's only two host
142
+ * failures: no LLM/route, or a call that threw. Both mean "multi-candidate
143
+ * plans will abstain" while single-candidate substitution keeps working, so
144
+ * they share one warning code. `selector-abstain` is not a host fact and is not
145
+ * mapped (review row 49).
107
146
  */
108
147
  const RECEIPT_DEGRADATION = [
109
148
  { code: 'projection-skipped:no-spill', degraded: ERR_HOST_NO_SPILL },
@@ -113,6 +152,10 @@ const RECEIPT_DEGRADATION = [
113
152
  // The substitution refusal writes the stable code itself, so a status built
114
153
  // without host facts still reports the reason the decision path recorded.
115
154
  { code: ERR_HOST_NO_TOKENMETER, degraded: ERR_HOST_NO_TOKENMETER },
155
+ // Only absence is a capability fact. `selector-error` is a call failure that
156
+ // may be transient and is summed over all history, so mapping it here would
157
+ // mark a healthy host degraded forever (review qr5#4).
158
+ { code: 'selector-unavailable', degraded: ERR_HOST_SELECTOR_UNAVAILABLE },
116
159
  ];
117
160
  /** The scope document's caller-writable fields. Everything else is store-owned. */
118
161
  const PATCH_FIELDS = ['mode', 'workspaceIds', 'shadow', 'projection'];
@@ -158,6 +201,8 @@ function replayOf(receipt, fallback) {
158
201
  async function aggregate(receipts, fallbackHorizon) {
159
202
  const counts = Object.create(null);
160
203
  let substitution = 0;
204
+ let substitutionAvoided = 0;
205
+ let avoidedSeen = false;
161
206
  let projectionGross = 0;
162
207
  let projectionGrossReplay = 0;
163
208
  let retrievalContentReplay = 0;
@@ -184,6 +229,26 @@ async function aggregate(receipts, fallbackHorizon) {
184
229
  if (typeof saved === 'number' && Number.isFinite(saved))
185
230
  substitution += saved;
186
231
  }
232
+ // The lower estimate is the skipped request's own total, summed over every
233
+ // receipt that carries it (the settled line is its producer). Presence is
234
+ // tracked separately from the value: a receipt carrying `0` is a
235
+ // measurement, while no receipt carrying the field means "not measured"
236
+ // and the key is omitted from `status` rather than reported as zero
237
+ // (review row 7).
238
+ // Pair the two sums on the same receipt: a rollover settlement writes a
239
+ // numeric lower bound with `saved_input_tokens: 'unknown'`, so summing the
240
+ // lower over a superset could report a floor above the ceiling
241
+ // (review qr5#2). A receipt that carries only one side contributes to
242
+ // neither.
243
+ const avoided = receipt.avoided_total_tokens;
244
+ const upper = receipt.saved_input_tokens;
245
+ if (typeof avoided === 'number' &&
246
+ Number.isFinite(avoided) &&
247
+ typeof upper === 'number' &&
248
+ Number.isFinite(upper)) {
249
+ substitutionAvoided += avoided;
250
+ avoidedSeen = true;
251
+ }
187
252
  if (receipt.kind !== 'projection')
188
253
  continue;
189
254
  const replay = replayOf(receipt, fallbackHorizon);
@@ -249,6 +314,7 @@ async function aggregate(receipts, fallbackHorizon) {
249
314
  return {
250
315
  counts,
251
316
  substitution,
317
+ ...(avoidedSeen ? { substitutionAvoided } : {}),
252
318
  projectionGross,
253
319
  projectionGrossReplay,
254
320
  retrievalContentReplay,
@@ -415,10 +481,20 @@ function degradationCodes(observed, read, host, fixedOverhead, missingMounts = [
415
481
  codes.push(ERR_HOST_NO_ESTIMATOR);
416
482
  // `spillStore` matters only in apply mode; shadow mode never touches it
417
483
  // (design §5.4), so reporting it while projection is `shadow` would be noise.
418
- if (host?.hasSpill === false && read.doc.projection === 'on')
419
- codes.push(ERR_HOST_NO_SPILL);
484
+ // Presence and capability are separate: an absent store and a present store
485
+ // without `saveText` need different repairs, so they get different codes.
486
+ if (read.doc.projection === 'on') {
487
+ if (host?.hasSpill === false)
488
+ codes.push(ERR_HOST_NO_SPILL);
489
+ else if (host?.spillUsable === false)
490
+ codes.push(ERR_HOST_SPILL_UNUSABLE);
491
+ }
492
+ // A present registry that cannot list is not an absent one: the operator is
493
+ // told which of the two host states to repair (review row 6).
420
494
  if (host?.hasWorkspaceRegistry === false)
421
495
  codes.push(ERR_HOST_NO_WORKSPACE_REGISTRY);
496
+ else if (host?.workspaceRegistryBroken === true)
497
+ codes.push(ERR_HOST_WORKSPACE_REGISTRY_BROKEN);
422
498
  // A missing mount is a wiring failure, not a capability absence: the plugin
423
499
  // is loaded but at least one of its four integration points is not, so the
424
500
  // ledgers cannot be trusted to describe what it is doing.
@@ -473,6 +549,9 @@ async function statusCommand(deps) {
473
549
  totals.legacyRetrievalCost;
474
550
  const saved = {
475
551
  substitution: totals.substitution,
552
+ ...(totals.substitutionAvoided === undefined
553
+ ? {}
554
+ : { substitution_avoided: totals.substitutionAvoided }),
476
555
  projectionGross: grossReplay,
477
556
  projectionNet,
478
557
  retrievals: totals.retrievals,
@@ -514,6 +593,7 @@ async function statusCommand(deps) {
514
593
  ...(deps.host?.hasWorkspaceRegistry === undefined
515
594
  ? {}
516
595
  : { hasWorkspaceRegistry: deps.host.hasWorkspaceRegistry }),
596
+ ...(deps.host?.hasSpill === undefined ? {} : { hasSpill: deps.host.hasSpill }),
517
597
  };
518
598
  return { ok: true, data };
519
599
  }