Observability and vocabulary — agent reference

The names that identify work as it moves through the Factory: work identities, stored events, command and aggregate prefixes, diagnostics channels, recorded times, codes, protocols and deliberate duplicates. It records what src/ stores and publishes, and the rules new code follows so that every lane names things one way. Nothing here grants Authority or feeds a decision: diagnostics and views built on these names are never Evidence.

Status: Current source catalogue; independent source and documentation review passed. The acceptance record records verification; required CI is tracked in the canonical status. The stored-name tables describe current source, including lifecycle scheduling, discovery sources, service access and the bet modules. WorkRef, callId and the delivery diagnostics below remain planned: no delivery composition or work-trace projection exists. A recorded schedule, batch or ask does not prove a live scheduler, a sent message or applied authority.

Source contracts remain in the module references; this page owns only the shared name registry. The catalogue tests compare it with source. Acceptance evidence belongs in the build review.

Work identity

WorkRef

A WorkRef names one unit of work across modules, so records, diagnostics and views can be joined without parsing IDs. It is derived from identities the records already hold. It is never random, never a path, and never an input to an admission or any other decision.

• The state digest is the first 12 hex characters of the SHA-256 of the state directory's real path, as UTF-8 bytes. The real path is realpathSync.native of the resolved directory: absolute, with no symbolic link in it. The fixture CLI keeps the journal, the Evidence store, the fences and the workspaces under that path (withState in local-factory.ts).
• A relative or linked spelling of one state directory gives one WorkRef. A moved or renamed directory gives its Runs new WorkRefs, and no stored record changes.
• A fixture Run's runId is unique only within its state directory, so its WorkRef carries the state digest.
• A WorkRef never enters a command ID, an aggregate ID or a payload. New event data carries the fields a WorkRef derives from (for a Slice, productId and sliceRef), so a view computes it without parsing an ID.
• The fixture WorkRef run:<state>#<runId> is not Execution's aggregate ID run:<runId>: # is outside the journal's ID grammar, so the two cannot be confused.
• Spans inside a unit of work are identities the records already hold. They are a journal commandId, a gate dispatchId (32 hex), an Attempt ID (<runId>/<epoch>), an Evidence ref, a prepared intent's digest and a Repository observation ID.

callId

A planned callId identifies one CLI invocation or one HTTP request, for tracing only. It is random per call, for example from crypto.randomUUID(), and appears only in diagnostics messages, the operations log and error bodies (as requestId). It never enters a command ID, payload, event or stored record. The journal replays only an identical command, so a value that differs between two tries of one command would turn its replay into a conflict.

Journal events

A command records its events in its aggregate's history, each with a pending outbox row that nothing delivers (Command journal). An event's type and data are stored history that views read, so a type never changes and a new data shape is a protocol revision.

Naming rule for new events

• A new event type is <prefix>.<subject>-<past participle> in lower-case kebab words, such as gate.slice-frozen or delivery.verdict-recorded. It fits the journal's ID grammar: 1–128 characters of A-Z a-z 0-9 . _ : / -, starting with a letter or digit.
• <prefix> is the module's registered event prefix (Command and aggregate prefixes); no two modules share one.
• The subject names what the command recorded, and the past participle what happened to it.
• New event data carries the fields its WorkRef derives from, and at (Time).
• Stored types that predate the rule, such as run.submitted, attempt.claimed and gate.bound, keep their names, because a rename would rewrite history.

Stored event types

Each table names the emitting function and top-level data fields. verification.reported is retained history only. A record-valued payload follows the linked module contract; the catalogue scanner checks literal fields, not all indirect schemas.

Execution (src/execution.ts), in aggregate run:<runId>:

Guarded verification (src/local-factory.ts, src/attempt-ledger.ts), in the same fixture journal. The ledger records each event through its private #create, and each record is its aggregate's state.

Portfolio (src/portfolio.ts) and Project guidance (src/project-guidance.ts):

Product gate (src/product-gate.ts), in aggregate gate:product:<productId>. The names are the EVENT table, and each command emits exactly one event.

Delivery records (src/delivery-records.ts): one create-once aggregate per record, written by command record:<aggregate ID> through the private #create. The record itself is the aggregate's state.

branch-health (src/branch-health.ts):

discovery-sources (src/discovery-sources.ts):

lifecycle-schedule (src/lifecycle-schedule.ts):

owner-digest (src/owner-digest.ts):

owner-policy (src/owner-policy.ts):

service-access (src/service-access.ts):

attempt.* names two families of events on different aggregates with different data: Execution's claims and settlements, and the ledger's records. Both are stored, so both stay.

Command and aggregate prefixes

Command IDs and aggregate IDs share the journal's ID grammar. Command IDs are journal-wide: once one is recorded, any other use of it in that journal conflicts (CommandConflictError). So each module's prefixes stay distinct, and no prefix, with its separator, begins another module's.

• Shared-journal collisions. Portfolio registration and Execution still accept caller-chosen journal IDs. A collision with a derived command ID can block that command permanently. Guidance now refuses new non-prefixed IDs inside the decision, preserving exact legacy replay.
• Planned service uses. The service-use: WorkRef is not an implemented use ledger or an authority grant.

Current additional prefixes

Rule for new prefixes

• A module registers its aggregate prefixes, command-ID prefixes and event prefix on this page in the change that adds its first command. This rule and the event rule apply to the lifecycle and service-access modules from their first increment.
• A command ID is derived from the command's own inputs where it can be, so a retry repeats it exactly. A random part (an owner token, a dispatch ID, a cancellation request) is chosen once and reused for every try of that command.
• A prefix ends with a separator (:, / or -), and neither it nor any registered prefix begins the other.
• The WorkRef forms slice:, occurrence: and service-use: are not journal prefixes.

Diagnostics channels

Modules publish diagnostics on node:diagnostics_channel. A diagnostic is never Evidence (core spec G4) and never read by a decision, and the publishing module stores none. publish runs each subscriber synchronously inside the call, which is how fault tests stop, kill or revoke at an exact point.

Rule for new channels and events

• One channel per module, named sf:<module>.
• Event names are <subject>-<past participle> in lower-case kebab words; the channel already names the module.
• A message holds names, identifiers, codes, counts and digests only: never payload text, file content, paths or credentials.

A message is one frozen object with these members.

Existing channels

These names stay as they are: fault and ordering tests subscribe to them, and renaming an event breaks those tests (as Repository records for its own). Their messages predate the rule: several carry paths, launched carries the sandbox profile text, and sf:producer keys its messages by phase.

The sf:delivery events

The delivery composition's channel (DELIVERY_CHANNEL = "sf:delivery", core spec §3.5) is not built. Its events are this closed list, published at exactly these points, and fault tests name them in KILL_AT, STOP_AT, REVOKE_AT and STOP_INTENT_AT (core spec §8). A journal command needs no event, because its command-ID prefix already gives fault points before and after it (KILL_BEFORE, KILL_AFTER). An event marks only what a prefix cannot: the point just after an effect outside the journal and before the record that follows it, or a synchronous window before an effect.

These names supersede the core spec's. Its final-read, invoking, guard, prepared and admitted (§5, I7 and I8; §8, rows A2, A3, A5, A6 and R12) become final-read-passed, invocation-started, guard-entered, intent-prepared and integration-admitted. Delivery code and its fault tests use the names in this table.

• Every message carries event and productId, and callId when the call has one. It carries workRef for every event except the first three, which concern the Product and no Slice.
• commandId, where listed, is the gate command that admitted the work: the production admission for candidate-sealed, and the dispatch for the others.
• When invokeOnce claims the intent, the two channels interleave in this order: integration-admitted, final-read-passed, invocation-started, integration-claimed, guard-entered, then integration-withheld, or integration-submitted and integration-acknowledged, and last invocation-returned.

Time

• A new command's payload carries at: one ISO 8601 UTC instant with milliseconds, such as 2026-10-02T09:00:00.000Z (the gate's TIMESTAMP form), which the caller reads once. Its event repeats it. A re-issued command with another clock value is another payload, so it conflicts and is re-read, never retried (core spec §1).
• The journal records no commit time and is not migrated to add one. Where no record holds a time, a view says "time not recorded" and never interpolates one.

Codes

Rule for new results

• A new result carries code, one word of a closed union of lower-case kebab words, and detail, 1–280 printable ASCII characters. That is the core spec's text rule: longer text is cut with a trailing ..., and any other character becomes ?.
• Stored records discriminate on kind; operation results discriminate on status.
• A refusal is a returned result or a thrown error, never a journal record: refusals record nothing.
• A pre-effect seam's refusal reason (the collector's CollectGate, Repository's IntegrationGuard) is <code>: <detail>, cut to the guard's 1–256 printable ASCII characters.
• The first result in this form is the gate's currentCheck (product-gate.ts, refactor step R4), whose codes are CurrentCheckCode; seamAnswer (product-gate.ts) gives its refusal to either seam as that reason.
• admitDispatch answers an exact replay with reason: "REPLAYED": history, never a refusal and never a permit.
• Existing codes keep their spelling, because callers and tests read them. Composition roots map them to nine families through exhaustive satisfies tables.

A composition root's table for the Evidence store's codes shows the shape. It is a sketch, since no such table exists in src/, and each of these codes has one meaning in evidence.ts.

type CodeFamily = "invalid" | "not-found" | "stale" | "conflict" | "limit" | "corrupt" | "unavailable" | "unknown-effect" | "internal";

const EVIDENCE_FAMILY = {
  "invalid-input": "invalid",
  "invalid-id": "invalid",
  missing: "not-found", // "evidence <id> does not exist"
  corrupt: "corrupt",
  conflict: "conflict", // "already exists and is not identical"
} as const satisfies Record<EvidenceErrorCode, CodeFamily>;

A missing code, an extra key or a code added to EvidenceErrorCode later fails the typecheck, so the table stays exhaustive. Some codes have more than one meaning: Portfolio's CONFLICT, for one, also reports a stream that kept changing during an import. The reviewed table that first needs such a code maps it, not this page.

No family names a refusal by Authority: the gate's REVOKED, STOPPED, NOT_OWNER, OUT_OF_SCOPE and OWNERSHIP_PROOF, the core spec's DeliveryError denied and the Dashboard's FORBIDDEN. The first composition root that maps them decides their family, in its reviewed table.

Existing vocabularies

Assurance, Repository Assurance and the fixture worker throw a plain TypeError for malformed input. A producer's DispatchGate refuses with GateRejection, whose code is any 1–32 characters of A-Z 0-9 _, not a closed union. One meaning has several words: not found is NOT_FOUND, not-found, missing or RUN_NOT_FOUND, and stale is STALE, VERSION_CONFLICT or STALE_ATTEMPT.

Protocols and frozen names

A stored or pinned shape changes through an explicit revision and compatibility contract, never by silently rewriting history (Factory model, invariant 9). A module may refuse an unsupported old revision; the protocol table records those boundaries. Frozen: every event type, command ID, aggregate prefix and protocol identifier on this page, the sf:repository event names, and the wording of Verdicts.

• Verdict wording. A Verdict's reasons are free text inside it, and they are protocol. Three checks compare the canonical JSON of a whole Verdict: the fixture recheck in guarded-verification.ts, the stored-report check observationProblem in factory-support.ts, and the gate's re-derivation in #integrationDispatch in product-gate.ts. A reworded reason would therefore make every stored fixture Verdict invalid and every retained repository proof NOT_VERIFIED. A mapping from a judgement to {code, detail} for display is never stored; refactor step R6 plans it (reasonOf).
• Pinned closures. The seven files of GUARDED_FIXTURE_SOURCES in fixture-manifest.ts are byte-frozen: a change makes every completed /2 Run present as invalidated. The eight files of COLLECTOR_SOURCES in repository-collector.ts are digested into every repository recipe: a change invalidates every repository Verdict made under the old digest. Both lists hold evidence.ts. Since refactor step R3 the collector's list holds Repository's wire grammar, repository-protocol.ts, in place of repository.ts: a change to Repository's Git, sealing or integration code no longer changes the digest, and a change to the grammar does.
• sf-evidence/1 takes no new record kind. A new kind, such as the lifecycle's Citation (sf-citation/1), is a format of its own, stored outside both closures.
• The fixture inspect document is /1 by default. FactoryResult in factory-support.ts, plus the CLI's exitCode, has no protocol member. A reader, such as step 1's run-briefing tool (increment 8), reads a document without one as sf-factory-inspect/1 and refuses any protocol it does not know. A later /2 names itself in that member.

Vocabulary

Three terms of the delivery core map to the Factory's one language as follows.

Some exported names mean different things in different files.

A file that needs both senses imports one under an alias. A rename waits for the file's next reviewed change, because every one of these files belongs to an accepted module.

Deliberate duplicates

Some definitions exist twice on purpose. A copy stays while its file is frozen, pinned by a receipt, or kept out of another module's import graph. Where a test holds a mirror equal, the table names it. The delivery records' own prepared-intent parser is gone (refactor step R3): the records and the gate parse a prepared intent with parsePreparedIntegration in repository-protocol.ts. The gate's and the records' validator kits, grammars and limit mirrors are gone too (refactor step R4): both take them from strict-input.ts, and the gate re-exports that file's GATE_LIMITS and exports RegExp copies of its PRODUCT_ID, SLICE_ID and GRANT_ID grammars, made from their sources, which neither module validates with. Two of the records' rules still differ from Repository's wire grammar: a Slice revision is bounded by GATE_LIMITS.maxRevision (999 999), where repository-protocol.ts takes any safe integer, and the records' HEAD_REF, still used for observations, is wider than its target-ref rule.

Changing it safely

What must stay true

• A change that adds an event type, command or aggregate prefix, diagnostics channel or event, protocol identifier or error code updates this page in the same change. A stored name never changes: its tables here grow, and no row is rewritten.
• A new event's data fields, and any field added to a stored event's data, are listed here in the same change, because a new data shape is a protocol revision.
• A change to the sf:delivery list comes before the delivery code that publishes it, with the fault tests that name it.
• The tables cite current files and symbols. A renamed emitting or publishing function, or a moved constant, fails the catalogue test until this page names the new one.

Tests and helpers

Run the catalogue and documentation tests, then rebuild the site. The catalogue checks stored event names and literal data fields, diagnostics names and keys, protocol identifiers, error-code unions and cited symbols. The documentation map classifies this cross-module reference; it has no matching topic guide.

Limits: the source scanner recognises { type, data } drafts in that order, literal or resolved constant/parameter types, and literal diagnostics event or phase names. An encountered unresolved form fails. Indirect payload schemas, command-ID derivation, clock provenance and duplicate meanings require review. Source-text coverage is not a journal migration, a live-data audit or runtime proof. Delivery events above are a reserved contract, not observed effects.