footprintjs - v11.2.0
    Preparing search index...

    Interface RunPolicy

    The run's policy: every dial resolved, plus the redaction rule and the mirror flag. Frozen.

    interface RunPolicy {
        commitValues: CommitValuesMode;
        mirror: boolean;
        readSources: boolean | { limits: Partial<ReadSourceLimits> };
        readTracking: RetentionPolicy;
        redaction?: RedactionRule;
        writeProvenance: WriteProvenanceMode;
        writeTracking: RetentionPolicy;
    }

    Hierarchy

    Index
    commitValues: CommitValuesMode

    Encoding policy for COMMIT LOG values (#13c-B) — the third dial of the family, and unlike its siblings it is lossless in both modes (it changes the log's encoding, never its information).

    • 'full' (default) — every surviving set path stores the full final value; byte-identical to the historical behavior.
    • 'delta' — array net-changes that are "base plus a tail" commit as an append trace verb storing ONLY the tail (the growing-history commit log becomes linear instead of O(N²) retained); deleteValue() commits as a real delete verb (replay removes the key instead of leaving key: undefined); bundles carry exactly ONE trace entry per surviving path. Replay (the one verb law — live state, materialise(), the redacted mirror, stateAt) reconstructs every step's full state exactly.

    Consumers that read bundle.overwrite[key] as "the full value written" must switch to commitValueAt(commitLog, idx, key) from foottrace — under 'delta' that value is verb-qualified (an append bundle holds only the tail). Path-tier consumers (findLastWriter, causalChain, narrative, lens highlights) are unaffected. The active mode is surfaced as getSnapshot().commitValues.

    Honest cost note: append detection is new wall work — an O(|base array|) structural prefix compare per array-set path per commit. On a hit the commit gets cheaper in both wall and heap; on a miss (prefix diverges) it pays compare + full clone. 'full' pays zero. Equivalent to calling executor.setCommitValues(mode) before run().

    mirror: boolean

    Keep a redacted mirror of the heap (a run with a redaction policy). Each runtime owns its own store.

    readSources: boolean | { limits: Partial<ReadSourceLimits> }

    Native, bounded scalar read-source occurrences (#113). Default false; memory-only in packet 3.

    readTracking: RetentionPolicy

    Policy for StageSnapshot.stageReads (#14). Default 'full' — a tracked read keeps a structuredClone of the value in the stage's read view (what lens/agentfootprint snapshots show). The clone is taken once for each object a key holds, not at every read (keptReads.ts); a key the stage itself has written is cloned at every read from then on. 'summary' records a cheap type/size/preview marker in its place; 'off' records nothing — no clone cost at all (reads of large values become ~free). Narrative and ScopeRecorder.onRead are identical in every mode. Caveat: under 'off' a stage's snapshot is indistinguishable from one that read nothing — auditing consumers that need "did it read?" without the value cost should prefer 'summary'. Equivalent to calling executor.setReadTracking(mode) before run().

    redaction?: RedactionRule

    The run's redaction rule — the ONE owner of the verdict (redaction.ts). Absent on bare frames.

    writeProvenance: WriteProvenanceMode

    Per-write read provenance (#P1) — the fourth dial of the family. Default 'off': zero cost, byte-identical commit logs. 'reads-prefix': every committed TraceEntry carries readKeys — the keys tracked-read BEFORE that write — enabling per-write causal attribution (causalChain's edgeAttribution: 'per-write' and variable slices). Cost: one small array copy per write. Snapshot discriminant: getSnapshot().writeProvenance.

    writeTracking: RetentionPolicy

    Policy for StageSnapshot.stageWrites (#13c-A) — the sibling of readTracking; the two dials are independent. Default 'full' — every tracked write structuredClones the value into the stage's write view (the historical behavior). 'summary' records a cheap WriteSummaryMarker (type/size/preview) per write; 'off' records nothing — stageWrites is absent from the snapshot.

    Observable consequences — what the policy DOES govern:

    • StageSnapshot.stageWrites (markers under 'summary', absent under 'off').
    • The commit observer payload: ScopeRecorder.onCommit(mutations) receives the retained _stageWrites entries, so it carries the same markers under 'summary' and an empty mutations bag under 'off' — deferred/observer consumers see exactly what retention stored.

    What it does NOT govern:

    • The writes themselves: shared state, the transaction buffer, and the COMMIT LOG are identical in every mode (commitLog values keep their full payloads — the lossless linear-cost fix for those is the commitValues dial, #13c-B).
    • Per-op ScopeRecorder.onWrite events — they fire with live values regardless (delivery tier, RFC-001's concern), so narrative output is identical in every mode.
    • Redaction: a policy/per-call-redacted write stores '[REDACTED]' under 'full' AND 'summary' (redaction takes precedence over the dial; a marker would leak size/preview), and nothing under 'off'.

    Caveat: under 'off' a stage's SNAPSHOT is indistinguishable from one that wrote nothing — but unlike readTracking: 'off', the commit log still records every net change, so "did it write?" stays answerable. Equivalent to calling executor.setWriteTracking(mode) before run().