Historical qualification: The bounded local record for source 7cf4b26e retains its exact check and review evidence. Current gates are recorded in the build review.
Historical bounded qualification, 3 October 2026: independent source and retained installed stage/concert evidence passed for the frozen local profile. This supersedes earlier source/package-pending statements below for that bounded profile. Historical 7cf combined full checks and independent evidence acceptance passed for the bounded local profile; complete stress/adoption matrices, exact-final-head CI and live commissioning remain separate. Reviewed scope.
Records each registered Product's core values (0–8 ordered values, each a statement and an application rule) as immutable, digest-bound revisions in the Command journal, and resolves pins to exactly the revision they name.
Status: "Accepted local domain and browser interface" (build review row "Project guidance / Attention", build review). Receipt: disposition accepted-local, scope "Local project guidance, source-derived attention and blocker resolution views", base 8ada02a. At that historical receipt no planner consumed Guidance, no Delivery authority was added, and all 35 epics were open; all 42 current epics remain open. The E29 identity seam with its private package consumer and the E34 versioned eight-value extension are accepted locally (1 October 2026); reviews and checks: review evidence · E34 evidence · acceptance receipt. E34's compatibility evidence uses disposable stores and no live migration has run; broader adoption remains open. Task guide: save project values. This reference owns the guidance contract; Dashboard reference owns the HTTP routes and editor interface.
The command-identity integration receipt records R8 acceptance and preserves the earlier evidence separately. The additive surplus-history correction record records the narrow #63 stored-history correction and its independent qualification. The correction is merged; required merged-main verification remains open.
Open gates: live planning qualification, any authorised live append of eight-value guidance, final combined CI and publication (see Trust scope and the acceptance receipt).
Factory consumers: native Knowledge advice and the prepared-prefix concert consume an exact retained Guidance pin and owner decision without granting Delivery authority. The Dashboard server's guidance routes and values editor, and scripts/factory-guidance.ts rehearse, which saves on a byte copy of a journal and never writes the source. The core is also imported by Guidance acceptance, which no Factory command runs. Composition gives the calls.
- Source: independent core
src/project-guidance-core.ts, compatible Factory adaptersrc/project-guidance.ts; browser editorapps/dashboard/src/guidance-draft.tsandapps/dashboard/src/views/ValuesPage.tsx(route/projects/:id/values) - Tests:
test/project-guidance-core.test.ts,test/project-guidance-namespace.test.ts,test/project-guidance-surplus-history.test.ts,test/project-guidance.test.ts,test/dashboard-guidance-attention.test.ts,test/dashboard-editor.test.ts; import rules intest/dashboard-boundaries.test.ts; child helpertest/helpers/guidance-child.ts
Intelligence: optional — project-guidance/summarise via frontier/low
Atomic rationale candidate v3
The separately authored v3 candidate adds setValuesWithRationale under an explicit current owner-decision GuidanceEditFence. The caller supplies a complete rationale and actual authority reference for this exact request; provenance or a Dashboard session cannot grant it. Values, before/after pins, full rationale, rationale digest and authority commit atomically at n+1 in the same Guidance aggregate. Independent source and earlier installed proof retain their original pins, including v3/rationale adapters. No live migration has run.
product-guidance/3, product-guidance-state/3 and guidance.values-set.v3 preserve the 0–8 value grammar, 280-character wording and 500 total revisions. Default guidanceDigest remains v2. The distinct transition digest excludes its derived after pin; the host request digest includes command identity. Rationale is at most 32768 bytes, prose fields 2048 bytes and request/complete transition 65536 bytes, with sixteen evidence references, eight alternatives/unknowns/trade-offs and eight affected current plus eight retired IDs. Whole overflow refuses.
The rationale names its exact before pin, wording/order delta, owner reason separately from author interpretation, trigger source/date/problem, support/contradictions, unknowns, no-change alternative, consequences/trade-offs/losses, concrete changed choice or reaffirmation, decision maker/authority, Product scope, immediate prospective effect and review/reversal conditions. A reversal names an earlier exact v3 transition and the consequences retained/undone. Structural completeness never establishes semantic adequacy. Current/legacy permissions still constrain effects; existing Slices retain their original Guidance pins.
transition(pin) returns one full rationale by exact pin; old revisions return rationale-not-recorded. Minimal v3 snapshots carry rationaleRef; history has whole-record continuation below 64 KiB. Original v1/v2 snapshots, digests and receipts remain exact, including replay after v3. New legacy writes after cutover refuse with MIGRATION_REQUIRED inside the Journal decision. Old binaries refuse migrated history; no automatic migration occurs.
Current migration inventory: native core and Factory facade expose atomic v3; Dashboard DTO/view/server disclose its rationale reference and the existing editor becomes read-only for migrated Products. Dashboard same-fence binding and CLI rehearsal preserve recorded old replay and refuse fresh legacy writes. Proposal Ownership guidance-set-values/2, Guidance Acceptance and Provider Guidance Tools retain their original schemas, deadlines and unknown semantics. Upgraded Acceptance traverses v3 history to reconcile exact old witnesses; new /2 effects after cutover refuse. These adapters need separately qualified v3 profiles before new editing. Source two-layout proof covers native Acceptance and provider tools. A separately authored append-only supplement candidate is now described below; its bounded qualification scope is recorded in the build review; full acceptance remains separate from the atomic increment.
Dated recollection supplements candidate
appendRationaleSupplement(input) records a later, dated and attributed recollection under an independently qualified supplementFence. Its exact original Guidance pin must resolve through the native reader. The append requires current owner permission for the exact Product/request and durable retained text; READ/list/replay require current READ. Callback identity, synchronous once-only execution and exact return are checked, and callbacks close after return/throw. A missing seam is unavailable; no token, provenance or input reference authorises writing.
The new guidance-rationale-supplement/1 command and guidance-rationale-supplement-record/1 record retain owner recollection separately from author interpretation, source/date, evidence references and unknowns. The existing Guidance aggregate/revision/digest, original rationale and frozen Slices never change. A legacy pin still returns rationale-not-recorded; a supplement says originalRationale: "not-recorded" and originalChanged: false. A v3 supplement names its already-present original rationale without replacing it. These are later recollections, not contemporaneous evidence.
Each recorded original pin has a distinct bounded append-only guidance:product:<id>:supplements:<revision>:<digest> aggregate, at most sixteen records and 786432 state bytes. No slot is removed/reset; 17th append refuses. Request and one whole record fit 65536 bytes; complete recollection fits 32768 bytes, individual prose fields 2048 bytes, evidence references sixteen and unknowns eight. Future-dated recollections and whole overflow refuse. The supplement version is separate from the unchanged 500-value-revision ceiling. Same-ID payload conflicts and expected-version races refuse; original receipt replay never resamples its clock.
rationaleSupplements(original, before?) returns minimal exact references with whole-record continuation (nextBefore, currently null under the sixteen-record bound). rationaleSupplement(ref) returns one complete record. Neither list nor transition inserts a recollection into the original rationale. Source proofs cover authority/READ refusal, wrong pin, future date, overflow, 16/17 exhaustion, same-ID conflict, stale race, lost acknowledgement/reopen and late callbacks, plus the two physical native adapter layouts. No live migration or real owner recollection is recorded. The build review retains supplement evidence.
What it hides
- Storage. One journal aggregate per Product,
guidance:product:<productId>, written only throughCommandJournal.execute; aggregate version = revision; new saves append oneguidance.values-set.v2event per revision with state schemaproduct-guidance-state/2. Retained v1 records useguidance.values-setandproduct-guidance-state/1; their six-value parser is frozen. - Integrity. Every read of recorded guidance re-parses every event up to the aggregate version captured at the start of the read, recomputes each digest and checks the aggregate state equals the last revision. An observed event beyond that captured version must be accounted for by a later aggregate for the same Product with a safe-integer revision from 1 to 500, supported schema and valid digest; a missing, malformed or still-behind aggregate is
CORRUPT. A genuine intervening commit permits the original captured prefix to be returned: the later aggregate is only evidence that the tail committed, not a replacement snapshot. No read transaction, retry or repair is added. Callers get frozen, checked snapshots for the captured revision or a refusal. Revision 0 and a Product with no aggregate are computed without reading history. - Idempotency and concurrency. Command receipts, replay binding and optimistic revisions are mapped to one error type preserving the six legacy codes, plus explicit v3 authority/migration refusals.
- Registration. The core asks a caller-owned
GuidanceIdentityRegistrywhether the Product exists. The compatible Factory adapter reads the Portfolio registry. Neither path reads the checkout.
Public interface
The draft private package exposes software-factory/project-guidance from the core and software-factory/command-journal for caller-owned storage. The adoption guide gives an external example, dependencies and lifecycle. Its reviews and acceptance are under Status.
Constants (defined in the core and re-exported by the Factory adapter):
| Name | Value |
|---|---|
GUIDANCE_PROTOCOL | "product-guidance/2" (new saves) |
GUIDANCE_LIMITS (frozen) | maxValues: 8, maxTextLength: 280, maxRequestBytes: 16_384 (canonical {productId, values, provenance}), maxRevisions: 500, maxHistoryPage: 20 |
LEGACY_GUIDANCE_PROTOCOL | "product-guidance/1" (old revisions and revision zero) |
DIRECT_ENTRY (frozen) | { origin: "direct-entry", note: null } |
New command IDs must start with guidance-. The decision rejects other new IDs without writing; the journal still replays an exact recorded legacy ID and refuses mismatched reuse as CONFLICT. The existing command grammar below remains valid for replay. The browser already creates guidance-<id>. Command payload and receipt result shapes remain unchanged across guidance versions.
Input rules (not exported): command ID /^[A-Za-z0-9][A-Za-z0-9._:\/-]{0,127}$/; Product ID /^[a-z0-9][a-z0-9-]{0,62}$/; value ID /^[a-z0-9][a-z0-9-]{0,39}$/, unique within a revision; each text field (statement, application, note) is 1–280 UTF-16 code units, well-formed, no outer whitespace, and no control, U+2028/2029, U+202A–202E, U+2066–2069 or U+FEFF characters (UNSAFE_TEXT). A pin digest is 64 lower-case hex characters (DIGEST); a stored recordedAt must be YYYY-MM-DDTHH:MM:SS.mmmZ (INSTANT) and round-trip through Date (instantOf), and the clock's toISOString() must match INSTANT; revisions are non-negative safe integers. A setValues or resolvePin input must have exactly its fields (accessors, extra or missing keys are INVALID); those inputs are first canonicalised whole, so JSON_LIMITS (1 MiB, depth 64) also apply as INVALID. Stored state, events and command results are held to the same exact shapes, but a failure there is wrapped as CORRUPT (stored). Constructor options and the history page object are read field by field, not shape-checked. Internal names: EVENT, STATE_SCHEMA, HISTORY_PAGE = 500 (the readHistory page size).
class ProductGuidance
- Core:
constructor(journal: CommandJournal, identities: GuidanceIdentityRegistry, options?: ProductGuidanceOptions). - Factory adapter: the existing
constructor(journal: CommandJournal, options?: ProductGuidanceOptions)selects Portfolio membership and delegates to the same core. Existing imports and error classes remain compatible. ProductGuidanceOptions { now?: () => Date }suppliesrecordedAt. A non-CommandJournalisINVALID. The caller opens and closes the journal; guidance neither owns that lifecycle nor creates storage.- Read:
current(productId: string): GuidanceSnapshot(revision 0 when unset)revision(productId: string, revision: number): GuidanceSnapshothistory(productId: string, page?: { before?: number; limit?: number }): GuidanceHistory: newest first,limit1–20 (default 10),beforea positive integerresolvePin(pin: GuidancePin): GuidanceSnapshot
- Write:
setValues(input: SetValuesInput): SetValuesResult
Function: guidanceDigest(productId: string, values: readonly GuidanceValue[], provenance: GuidanceProvenance | null = DIRECT_ENTRY, protocol: GuidanceProtocol = GUIDANCE_PROTOCOL): string: SHA-256 hex of canonical {protocol, productId, values, provenance}; the default is v2. For a recorded v1/v2 snapshot, pass its protocol explicitly. For v3 use its retained transition digest; the legacy helper refuses v3. Revision 0 always uses ([], null, LEGACY_GUIDANCE_PROTOCOL). An unsupported protocol is INVALID. It is a hashing helper, not a guidance validator: it serialises through JSON.stringify (getters and toJSON run), then applies only canonicalJson's own checks (well-formed strings, JSON_LIMITS), which escape as InvalidInputError, not GuidanceError; native serialisation errors also propagate. None of the value, provenance or Product rules above are applied, so validate guidance inputs first.
Identity contract: GuidanceIdentityRegistry { hasProduct(productId: string): boolean }. Supply a synchronous data method, on an object or its prototype; accessors and missing/non-callable methods are INVALID. Lookup examines at most 32 objects and refuses cyclic or deeper prototype chains. The method's receiver is preserved, including private fields on a class registry. Each public operation validates the canonical Product ID before calling the captured method once. Exactly true admits it, false is NOT_FOUND, and any other result (including a Promise or thenable) is INVALID; no thenable is awaited. A registry exception passes through. All refusals occur before any guidance write. Membership is checked before command replay too, so after a registry revokes a Product, replaying a recorded command ID returns NOT_FOUND; that says nothing about whether the earlier save committed. Restore membership and replay the same command ID to settle the outcome.
The host owns identity persistence and must keep each ID bound to the same Product for the journal's lifetime. Removing membership denies reads, pins and exact replay as well as new writes; it never deletes or rewrites revisions. Reintroducing that ID exposes its old history. Registration is a scope check by trusted caller code, not authentication or delivery Authority, and is not atomic with a separate registry: the host owns synchronisation and any stronger revocation requirement. Methods are captured at construction; change the registry's data, or construct a new reader to substitute its method.
Types
GuidanceValue { id, statement, application }GuidanceProvenance { origin: "direct-entry" | "document-summary"; note: string | null }(noterequired fordocument-summary)GuidanceProtocol = "product-guidance/1" | "product-guidance/2"GuidanceSnapshot { protocol, productId, revision, digest, recordedAt: string | null, provenance: GuidanceProvenance | null, values }, deep-frozenGuidancePin { productId, revision, digest }SetValuesInput { commandId, productId, expectedRevision, values, provenance? }(defaults toDIRECT_ENTRY)SetValuesResult { productId, revision, digest, recordedAt, replayed }GuidanceHistory { productId, revision, revisions, nextBefore: number | null }- Errors:
GuidanceErrorCode = "INVALID" | "NOT_FOUND" | "STALE" | "CONFLICT" | "LIMIT" | "CORRUPT";class GuidanceError extends Error { readonly code; readonly currentRevision: number | null }
Browser editor (guidance-draft.ts, pure, run under Node by dashboard-editor.test.ts; its header comment names dashboard-format.test.ts, which does not import it): draftOf, typed, payloadOf, sameValues, isDirty, problemsOf, changesBetween, changeText, provenanceText, newValueId (v- + 1–10 [a-z0-9]), move, operationFor, failureOf, and types Draft, FieldProblem, ChangeSummary, Operation, SaveFailure = "stale" | "uncertain" | "refused". ValuesPage.tsx exports ValuesPage({ productId: string; period: PeriodId }), titled "Core values" and reached from the project page as "Add values", "Edit values" or, with edits disabled, "View values", and ValueList({ values: readonly GuidanceValueDto[] }), which ProjectPage.tsx also renders on the project overview, so a presentation change there shows in both places. Its history disclosure requests ?limit=10 (api.ts) and shows only that newest page, saying older revisions are kept; there is no paging control, so older revisions are reachable through the API's before parameter only.
Invariants and guarantees
- One revision per accepted command. Revision 0 is unset (
recordedAt,provenancenull, no values). Each acceptedsetValues, including one that clears the list, adds exactly one revision. Identical content under a new command ID is still a new revision. Tests: "revisions survive a real restart…clearing is a revision"; "…stale and writes nothing" (re-save under a new ID). - History is append-only.
revision(p, n)returns exactly what was recorded. The module has no delete, rewrite or retention path. Value IDs are caller-supplied: the domain checks only their syntax and uniqueness within a revision and does not enforce continuity between revisions, so a caller keeps an ID when rewording or reordering (the editor does; the restart test does so in its inputs). - Digest binding. The digest covers protocol, Product, ordered values and provenance, not revision or
recordedAt, so two revisions can share a digest; a pin carries both. The same values with different provenance have different digests (test "provenance is part of each revision"). - Pins never move.
resolvePinreturns the pinned snapshot whatever is edited later; a digest mismatch isCONFLICT, never upgraded. A pin moved to another Product isNOT_FOUNDwhen that Product has no such revision (the tested case) and otherwiseCONFLICT, because the digest names the Product (test "a pinned revision resolves to exactly what was pinned"). - Validation before writing. Malformed, oversized or unregistered input, and a bad clock value, are refused before
execute; the 501st revision is refused inside the decision, which also writes nothing. The journal footprint is unchanged (test "invalid, oversized, unregistered or cross-Product input writes nothing"). The v3 candidate adds a permanent 500/501 source regression; historical invalid-clock qualification is retained. - Idempotent by command ID. The journal compares aggregate,
expectedRevisionand canonical payload. An exact repeat returns the recorded result, originalrecordedAtincluded, withreplayed: true, writes nothing and works after later revisions; any difference isCONFLICT(test "an exact command replays…"). - Optimistic concurrency. A non-current
expectedRevisionisSTALEwithcurrentRevision; nothing is merged, rebased or retried. Two real processes at one revision: exactly one wins, three rounds (test "two real controllers…"). - Reconcile before trusting.
current,history,setValues, andrevisionandresolvePinfor n ≥ 1, run#reconciled;decideSetre-validates the previous state inside the transaction. Afterexecute, every result must carry the outcome's version and this request's digest, and a replayed one must also match the recorded revision's digest andrecordedAt. Any disagreement isCORRUPTfor that Product only; other Products still read and no edit writes over it (test "stored guidance that disagrees…"). Exceptions: revision 0 (viarevisionorresolvePin) is the computed unset snapshot, andcurrentof a Product with no aggregate is the same, both returned without reading history. - Isolation. Guidance never reads the checkout, runs Git, writes the registry or records Product facts;
productView(...).deliveryAuthoritystays"absent"(test "an unavailable checkout does not block guidance…"). Values are never copied between Products. - Text is data. Values are stored verbatim (hostile HTML round-trips unchanged); the dashboard escapes
<,>,&in every JSON body. - Import boundary. The core imports only
./canonical-json.ts,./journal.ts,node:buffer,node:crypto; its complete local runtime closure is core, Journal, canonical JSON and errors. Only the Factory adapter imports the core insrc; its existing consumers remaindashboard-server.tsand the type-onlydashboard-view.ts. Exact compiler graph and mutation checks enforce both boundaries (module-graph.test.ts,dashboard-boundaries.test.ts).
Failure semantics
GuidanceError.code | Raised when | Written? | HTTP (toHttpError) |
|---|---|---|---|
INVALID | Malformed input, bad pin shape, a revision that is not a non-negative safe integer, clock outside INSTANT, malformed registry or non-boolean membership result | No | 400 BAD_REQUEST |
NOT_FOUND | Unregistered Product, or no such revision | No | 404 |
STALE | expectedRevision not current (currentRevision set) | No | 409 STALE |
CONFLICT | Command ID reused with other input; pin digest mismatch | No | 409 CONFLICT |
LIMIT | Over 8 values, over 16 384 payload bytes, or a 501st revision | No | 409 CONFLICT |
CORRUPT | Stored state, history or receipt disagree | No (refused before writing, or on a replay); the post-execute result check would report a defective fresh commit as CORRUPT after the write | 500 CORRUPT |
- Other errors pass through unchanged: journal errors (busy, read-only, closed), caller registry errors (including
PortfolioErrorfrom the Factory adapter), and anything thenowcallback throws. Native errors are not wrapped: a clock that returns an invalidDatethrowsRangeErrorfromtoISOString()before anything is written, and a storedrecordedAtthat matchesINSTANTbut is not a real date throwsRangeErrorfrominstantOfrather thanCORRUPT. The dashboard serves these as 500INTERNAL. A journal error duringexecuteleaves the outcome unknown to the caller. - Unknown is not failed. After an unknown outcome, retry the same command ID with identical input: a committed write replays; an uncommitted one records now, or returns
STALEif another revision landed. Never re-issue the change under a new ID until the first is resolved. - The editor follows this within one mounted page.
failureOfmaps status 0, ≥ 500,BUSYandINCOMPATIBLEtouncertain; the person then chooses "Retry save", andoperationForreuses the sameguidance-<id>operation while revision and trimmed values are unchanged; a draft changed since sends a new ID at the sameexpectedRevision, so a first save that did commit surfaces asSTALErather than being overwritten. The pending operation and draft live in component state only: a reload, navigation or "Discard changes" loses them.STALEkeeps the draft and shows both sides when the follow-up read of the current revision succeeds; if that read fails it becomesrefusedwith the draft kept. "Keep my draft" rebases explicitly. Anything else isrefused. - Retries: none inside the module. Repair: none;
CORRUPTpersists until the store is repaired by other means.
Trust scope
Established locally (the receipt, base 8ada02a, records the review, its findings and tests, and the full check):
- Revisioning, exact replay, stale refusal, two-process races, restart survival, pin stability, provenance binding and tamper detection of inconsistent state, history or receipts. All run over real SQLite journals in disposable directories.
- The HTTP command: guards, bounds, restart and replay, forced direct entry, edits with a missing checkout and no Git.
- Browser checks in one browser (Codex in-app) on synthetic fixtures at 1536×1024 and 390×844: save with history, disabled controls while saving, stale draft kept, explicit rebase, keyboard reorder, retire and restore. Live Factory shows six
document-summaryvalues at revision 1; other Products are unset.
Not established:
- Planning consumer. No planner, brief builder or provider reads guidance, and
resolvePinhas no caller insrc/. Any effect of values on decisions is unproven. - Independent distribution. The tarball consumer now exercises this core through named package imports, including alternate registries, restart, pins and failure cases (review evidence); the remaining E29 families are still required.
- Authority. Guidance grants no delivery Authority and changes no acceptance, Budget or safety constraint. Empty guidance is never a gate or an attention item.
- Identity. Provenance records where words came from, not who typed them.
document-summaryis accepted from any in-process caller and is not calibrated doctrine. The dashboard token guards the browser session; it does not name a person. - Tamper resistance. Digests are unkeyed SHA-256. Anyone with write access to the journal can rewrite event, state and receipt consistently and reads will accept it. An existing pin detects a change to the digest-covered content of its revision (Product, ordered values, provenance) but not to its
recordedAt, which the digest excludes. - Scale and durability. Every read of recorded guidance re-validates its full history (up to 500 revisions); no latency is measured. There is no rollover past 500, no migration, and no durability beyond the Command journal's own.
- Value. Any Verdict, release or customer-value claim.
Composition
- Depends on:
src/journal.ts(Command journal):CommandJournal.execute,readAggregate,readHistory,canonicalJson, andVersionConflictError→STALE,CommandConflictError→CONFLICT,DecisionError(unwrapped to itsGuidanceErrorcause),InvalidInputError;src/canonical-json.ts:jsonObjectEntriesfor exact-shape reads;- a caller-owned
GuidanceIdentityRegistryin the core. Only the Factory compatibility adapter addssrc/portfolio.ts(Portfolio):new Portfolio(journal).listProducts()for registration; aPortfolioErrorfrom that read passes through unchanged.
- Runtime and lifecycle: Node.js ≥26.8.1 with built-in SQLite and the Journal's filesystem permissions; no Git, checkout, server, scheduler, provider or sign-in is needed by the core. Importing it starts none. The caller owns storage and closes it after use. Old records, command/aggregate IDs, digests, revision bounds and pins remain unchanged. New saves use v2 and allow eight values. No automatic adoption or live data migration runs.
- Used by (Dashboard):
src/dashboard-server.ts:guidanceResponse→current;guidanceHistoryResponse→history(before1–501,limit1–20);guidanceRevisionResponse→revision(route…/guidance/revisions/:n,n1–6 digits);guidanceCommand→setValueswithprovenance: DIRECT_ENTRY. Reads open the journal read-only; the command usesCommandJournal.openExisting. The body is at most 24 576 bytes (DASHBOARD_LIMITS.maxGuidanceBodyBytes) and must be exactly{commandId, expectedRevision, values}, so aprovenancefield is refused.--no-guidance-editsmakes POST 403 while reads still work.src/dashboard-view.ts:guidanceDto(snapshot), a type-only import.- The browser reaches guidance only through HTTP DTOs (
GuidanceDto,GuidanceSaveRequestDto, …,DASHBOARD_PROTOCOL = "factory-dashboard/3").
- Not linked: Required actions and blockers (
src/attention.ts) cannot import guidance, and empty guidance is never an item. - Intended future caller: a brief pins
{productId, revision, digest}fromcurrent(), presents the applicableapplicationrules, explains trade-offs against them, and resolves withresolvePin.
Changing it safely
- Run:
- focused:
node --test test/project-guidance-core.test.ts test/project-guidance-surplus-history.test.ts test/project-guidance.test.ts test/dashboard-guidance-attention.test.ts test/dashboard-editor.test.ts test/dashboard-boundaries.test.ts; npm run typecheck;npm run checkbefore acceptance;- for
ValuesPage.tsxchanges,npm --prefix apps/dashboard run buildand a real desktop and mobile browser check.
- focused:
- Which tests prove what:
project-guidance-surplus-history.test.ts: retained real events ahead of a restored aggregate refuse recorded reads, pins, writes and replay without changing any row; a real second-connection commit returns the captured prefix; missing, behind, over-limit, wrong-Product, unsupported-schema and bad-digest later aggregates cannot excuse a tail; other Products remain readable;project-guidance-core.test.ts: two substitute identity readers without Portfolio/Git, reopen, membership withdrawal, malformed readers/IDs, lost acknowledgement replay, stale/conflict refusal, corruption and Product isolation;project-guidance.test.ts: also proves Factory/core parity in both directions for shared revisions, digests, pins and replay;project-guidance.test.ts: domain invariants 1–9 (restart, replay, conflict, stale, races, bad input, missing checkout, pins, provenance, corruption), with an additive permanent v3 500/501 regression; historical invalid-clock qualification is retained;dashboard-guidance-attention.test.ts: HTTP guards, bounds, restart, replay,STALE/CONFLICT, direct entry, missing checkout;dashboard-editor.test.ts: operation reuse, failure classes, draft rules, change summaries;dashboard-boundaries.test.ts: the import boundary and consumer list.
- Receipt: the receipt hashes evidence files under
<local evidence directory>(gitignored, not in this repository), not source, so a source change does not invalidate it mechanically. Treat any behaviour change as outside the accepted scope until a fresh independent review and new receipt. Update project guidance, dashboard and the build-review row. - Storage-affecting changes (retain explicit parsers for every supported version; never loosen the v1 parser).
#reconciledre-parses a Product's history through the captured aggregate revision on every recorded read except revision 0, so one stored record it can no longer validate makes every such read of that ProductCORRUPTand breaks its pins:- a recorded protocol, its digest inputs or their canonical encoding: every recorded digest is recomputed and compared (
snapshotOf); revision 0's computed digest can change too, making existing revision-0 pinsCONFLICT; - the value or provenance shapes: every recorded revision holds a provenance record and every non-empty one holds value records (
snapshotOf), so only a Product whose revisions are all empty survives a value-shape change; - removing support for an event or state schema: its recorded revisions fail (
#reconciled,stateSnapshot); revision-0 pins are unaffected, as revision 0 never reads storage; - the aggregate ID format (
aggregateOf): existing guidance reads as unset (revision 0) with empty history, and a pin to a recorded revision isNOT_FOUND. - A served-shape change needs a
DASHBOARD_PROTOCOLbump (dashboard-contract.ts:9).
- a recorded protocol, its digest inputs or their canonical encoding: every recorded digest is recomputed and compared (
- Keep in step: the editor's
INVISIBLEset withUNSAFE_TEXT; editor limits come from the servedlimits. - Reviewers check:
- validation and reconciliation still run before
execute; - no content shortcut bypasses command receipts;
STALEis never merged or retried;- replay still binds request and recorded revision;
- the HTTP path still forces
DIRECT_ENTRY; - the import boundary holds;
- any new consumer pins a revision instead of reading
current()implicitly.
- validation and reconciliation still run before
E29 review scope
This increment extracts the identity read contract without changing persistence or the editor/API. The original acceptance receipts remain historical evidence, not acceptance of the new seam. E29 has a bounded private tarball consumer, accepted locally (see Status); the other project/operations families remain open; E34 now adds a versioned eight-value representation; any live adoption remains a separate gate. No live guidance was migrated by this refactor.
E34 versioned saves (draft)
Every new save uses v2, even when empty or holding six or fewer values. V1 parsing, canonical digest inputs and revision-zero identity are unchanged. A new reader reconciles v1 followed by v2 and derives each historical replay digest from its recorded revision. History cannot return to v1 after v2. Pins remain {productId, revision, digest}. No prior event, receipt or revision is rewritten.
The actual pre-change package is frozen with its SHA-256 in test/fixtures/guidance-v1/provenance.json. project-guidance-v2.test.ts checks old→old, new→old, new→mixed and old→v2 refusal, lost acknowledgements, provenance and version tampering, revision-zero and recorded pins, and Product isolation. After v2 appears, the old reader reports CORRUPT for recorded guidance and refuses writes, including old command replay, with no persisted change. Its independent revision-zero lookup still works. Forward compatibility is not claimed; keep upgraded readers for Products with v2 history.
The Dashboard retains its existing factory-dashboard/3 shape: its digest is opaque and its limits come from the server. Existing browser code renders all rows and receives maxValues: 8; it neither truncates old nor new history. Unsupported Dashboard protocol versions remain refused. The public module exposes the v1/v2 snapshot protocol union; digest-helper callers must pass the recorded protocol when recomputing historical hashes.
The change was merged on 1 October 2026; its reviews and acceptance are under Status. Any authorised live append remains pending. Before that append, scripts/factory-guidance.ts rehearse saves the values on a byte copy of the journal with this adapter, reads them back, resolves the previous and new pins and writes a canonical report; it never opens or writes the source (rehearsal guide, tests in test/factory-guidance.test.ts, independent review pending). Compatibility tests use disposable stores only; no live Factory guidance was migrated.
Shared value implementation: common contracts. Owning errors, limits, stored identities and authority remain as specified above.
