footprintjs 9.46.0 → 9.47.0

package/dist/esm/lib/memory/redaction.d.ts

@@ -40,16 +40,41 @@
  * the facade held the verdict alone, and every path that wrote or read past
  * the facade — five of them — retained plaintext under a policy.
  *
- * TWO PLACEHOLDERS, BOTH HISTORICAL: the commit log and the mirror carry
- * `'REDACTED'` (`scrubPatch` / `redactPatch`, below — the strings unchanged since 4.x); every scope-tier view —
- * scope recorder events, `stageReads`/`stageWrites`, narrative — carries
- * `'[REDACTED]'`. Neither string changed in 9.19.0. The strings themselves are
- * owned by `memory/placeholders.ts` (`LOG_PLACEHOLDER` / `SCOPE_PLACEHOLDER`)
- * and spelled nowhere else in `src/` — this rule asks for the scope one by name.
+ * ONE VERDICT OWNER, ONE ENCODING OWNER (C4). This file DECIDES — the rule,
+ * and for a staged write {@link decideWrite} (the verdict),
+ * {@link inheritByIdentity} and {@link markStagedWrite} (the marks) — and is
+ * the engine's (L4, beside the run policy that carries the rule). The BYTES of a
+ * verdict are the record's: the frame hands its scrub (`whole`, or the
+ * `fields` inside the value — {@link scrubOf}) to `RecordFrame · write`, and
+ * the record's own scrub (`memory/scrub.ts`, L2) writes the log's placeholder
+ * at commit. Before C4 the scrub lived here too, so the record imported the
+ * engine's policy module to write a string.
+ *
+ * TWO PLACEHOLDERS, BOTH HISTORICAL, ONE PER OWNER: the commit log and the
+ * mirror carry `'REDACTED'` (`LOG_PLACEHOLDER`, `memory/placeholders.ts` — a
+ * record byte, written by `memory/scrub.ts`); every scope-tier view — scope
+ * recorder events, `stageReads`/`stageWrites`, narrative — carries
+ * `'[REDACTED]'` ({@link SCOPE_PLACEHOLDER}, below — the verdict's own).
+ * Neither string changed in 9.19.0 or since; each is spelled once in `src/`.
  */
 import type { StructuredErrorInfo } from '../errors/errorInfo.js';
 import type { RedactionMarks } from '../pause/types.js';
-import type { MemoryPatch } from './types.js';
+import type { WriteScrub, WriteVerb } from './RecordFrame.js';
+/**
+ * What the SCOPE CHANNEL carries where a value was scrubbed: a scope recorder's read, write and
+ * commit events, the `stageReads` / `stageWrites` retention, the narrative, a decision's evidence, an
+ * emit payload matched by `emitPatterns`, a pause payload's served form and a subflow's narrated seed
+ * (`onSubflowEntry`) — every value this verdict serves, unless its caller passes the log's string.
+ *
+ * Its twin is the RECORD's `LOG_PLACEHOLDER` (`'REDACTED'`, `memory/placeholders.ts`): the commit log,
+ * the redacted mirror and everything served from them. So NOT every recorder event carries this one:
+ * `onSubflowExit.outputState` serves the subflow's redacted mirror when a policy keeps one, and so
+ * carries the log's string (without a mirror — per-call marks alone — it is the subflow's heap
+ * retained under the rule, with this one). Both strings are historical and neither changed when it
+ * moved: this one was the constant `REDACTED` in this file until F4a, then `placeholders.ts ·
+ * SCOPE_PLACEHOLDER`, and since C4 it lives here again, beside the verdict that writes it.
+ */
+export declare const SCOPE_PLACEHOLDER = "[REDACTED]";
 /**
  * Declarative key/path redaction for recorded state and boundary records.
  *
@@ -127,6 +152,14 @@ export type RedactionVerdict = {
     readonly paths: readonly string[];
 };
 export declare const CLEAR: RedactionVerdict;
+/**
+ * The user-level NAME of `key` under `path` — the key itself at the top level, else the segments
+ * joined by a dot (`['profile'] + 'auth'` → `'profile.auth'`): what a verdict decides on, a mark
+ * holds, and the frame keys a stage's retained reads and writes by (`StageContext`). A name, not an
+ * address — a key may contain a dot — so it never goes into a trace path. No allocation for the
+ * common top-level key. (The record spells the same name for `readKeys`, `RecordFrame · noteRead`.)
+ */
+export declare function userKeyOf(path: readonly string[], key: string): string;
 export declare class RedactionRule {
     private policy;
     private diagnosticRule;
@@ -298,7 +331,7 @@ export declare class RedactionRule {
      * (declared or themselves inherited). Run-wide, by name, like a mark.
      */
     inheritFields(target: string, paths: readonly string[]): void;
-    /** The verdict of a key a mapper read — `runs` (the run namespaces) is selected when any namespaced key is. */
+    /** The verdict of a key a mapper read — `runs` (the run namespaces, `RUN_NAMESPACE`) is selected when any namespaced key is. */
     verdictOfRead(key: string, value: unknown): RedactionVerdict;
     /**
      * The retained / served form of a value at a path: the placeholder, a
@@ -381,6 +414,43 @@ export declare class RedactionRule {
     static scrubFields(value: unknown, paths: readonly string[], placeholder?: string): Record<string, unknown> | undefined;
     report(): RedactionReport;
 }
+/**
+ * Step 1 — THE VERDICT for one staged write: an explicit per-call flag (`setValue(key, value, true)`)
+ * makes the value secret whole under its user-level key; else the `active` rule decides from the
+ * user-level path; with none (no rule, or an inert one — the caller passes `undefined`), clear, with no
+ * verdict call and no path allocation (the no-policy fast path). Marks nothing.
+ *
+ * ```ts
+ * decideWrite(new RedactionRule({ fields: { card: ['number'] } }), [], 'card', false); // { kind: 'fields', key: 'card', paths: ['number'] }
+ * decideWrite(undefined, ['profile'], 'auth', true); // { kind: 'whole', key: 'profile.auth' }
+ * ```
+ */
+export declare function decideWrite(active: RedactionRule | undefined, path: readonly string[], key: string, explicit: boolean | undefined): RedactionVerdict;
+/**
+ * Step 2 — IDENTITY: an OBJECT the stage read under a selected name (`selected` — the frame's selected
+ * reads, filled by its tracked reads), written under another name (`s.person = s.profile`), keeps that
+ * read's rule, matched by identity: a whole read marks the new key, a `fields` read hands it the fields
+ * (re-based under the written path), and the verdict is asked again. A new object, a primitive, or a
+ * write already whole is selected by its own name only — `verdict` comes back as it is. Decided BEFORE
+ * the write, because the verdict needs it: an inheritance stays even if the write then fails to stage.
+ */
+export declare function inheritByIdentity(active: RedactionRule | undefined, verdict: RedactionVerdict, selected: WeakMap<object, RedactionVerdict> | undefined, path: readonly string[], key: string, value: unknown): RedactionVerdict;
+/**
+ * Step 3's input — a verdict's BYTES for the record (`RecordFrame · write`): nothing when clear, the
+ * whole value, or the fields inside it. No allocation on the default path (clear) or for a whole verdict.
+ */
+export declare function scrubOf(verdict: RedactionVerdict): WriteScrub | undefined;
+/**
+ * Step 4 — the MARKS a staged write leaves; call it only once the write staged, so a write that fails to
+ * stage marks nothing. A delete clears its key's mark (and any fields a mapper handed it) on `active`,
+ * the rule that was active as the write BEGAN — none when it was inert, even if user code marked the key
+ * during the write. A whole verdict marks its key — the key that DECIDED it (`verdict.key`: an ancestor
+ * for a nested write under a whole-selected key) — for the rest of the run on `rule`, the run's rule as
+ * it stands NOW (user code during the write may have installed one; an explicit mark is what makes an
+ * inert rule active). A mark is a run-wide NAME: it stays when the stage's commit fails or a retry
+ * discards the attempt — the safe side; only a staged delete removes one.
+ */
+export declare function markStagedWrite(active: RedactionRule | undefined, rule: RedactionRule | undefined, verdict: RedactionVerdict, path: readonly string[], key: string, verb: WriteVerb): void;
 /**
  * Path visits one walk may make — reachable only under a PATH-dependent
  * pattern over a value whose paths outnumber its objects (a linked history, a
@@ -518,35 +588,3 @@ export declare class MapperTaint {
     /** Does a value the mapper BUILT embed, by reference, a selected record it read or was handed? */
     private embedsSelected;
 }
-/**
- * The commit log's scrub: `patch` with {@link LOG_PLACEHOLDER} at every path in `redactedPaths` that
- * holds a defined value — the copy `recordCommit` records and feeds the redacted mirror.
- *
- * CLONE-FREE (9.33.0). The patch is the transaction buffer's commit-time payload, already the record's
- * own copy (`TransactionBuffer · commit` clones each surviving path once; the buffer is dropped at
- * commit), so the scrub copies only what it must not edit in place:
- *   - no path to scrub (no policy, no per-call mark — the common case) → `patch` ITSELF, no copy at all;
- *   - otherwise → a new root and a shallow copy of each container on a scrubbed path (`pathOps ·
- *     ownSpine`), every other subtree shared with `patch`. `patch` is never edited.
- * The engine called the public {@link redactPatch} (a whole `structuredClone`) twice per commit before
- * 9.33.0. The bytes are the same: a scrubbed path holds the placeholder, every other path the value the
- * buffer cloned (pinned by the 9.18.1 / 9.19.1 redaction byte tests).
- *
- * Paths are scrubbed in the set's order, against the tree as scrubbed so far: a path under one already
- * scrubbed finds a string, not a container, and is left alone (as before).
- *
- * INTERNAL — the result shares structure with `patch`. A caller outside the commit path wants
- * {@link redactPatch}.
- *
- * @param redactedPaths DELIM-joined paths (`TransactionBuffer`'s `redactedPaths`; a bundle's
- *   `redactedPaths` array works too).
- */
-export declare function scrubPatch(patch: MemoryPatch, redactedPaths: Iterable<string>): MemoryPatch;
-/**
- * Redacts sensitive values in a patch for logging/debugging — the PUBLIC scrub (`footprintjs/advanced`),
- * its contract unchanged since 4.x: a fresh deep copy of `patch` (`structuredClone`) with
- * {@link LOG_PLACEHOLDER} at every listed path that holds a defined value. Shares nothing with `patch`
- * and never edits it. (Moved here from `memory/utils.ts` in 9.33.0; the engine's own commit path uses the
- * clone-free {@link scrubPatch}.)
- */
-export declare function redactPatch(patch: MemoryPatch, redactedSet: Set<string>): MemoryPatch;