Transactional graph

Storage

All worktrees in a clone connect to one graphd at $(git rev-parse --git-common-dir)/lamina/. Linux and macOS use a Unix socket; Windows uses a repository-specific named pipe. Every request carries the random token stored in that runtime directory. Only graphd opens Ladybug read-write.

Resources and Statements

Resources use stable opaque ids and generic kinds. Human names are aliases. A Statement has subject, namespaced predicate, exactly one object or typed literal, optional scope, and semantic qualifiers.

The Statement id is a hash of normalized semantic identity. Duplicate proposals are idempotent. Evidence attaches to the same Statement. Reverse relationships are queried. Competing values for the same functional fact create one canonical Contradiction without deleting either side; independent qualified facts, such as workflow steps at different positions, remain distinct.

Versions and sessions

Every Git branch resolves to a GraphView and head GraphVersion. Explicit sessions stage several mutations against a base version. Publication compares the session base with the current branch head, validates, creates a version delta, updates materialized membership, and moves the head in one transaction.

Failed validation or publication never leaves a partial GraphVersion. A stale session remains inspectable until it is rebased or discarded.

A Git merge reconciles every parent GraphVersion. Compatible memberships are combined, while incompatible parent facts produce the same canonical Contradiction as a directly proposed conflict.

lamina session start
lamina session publish <id>
lamina session rebase <id>

CLI surface

lamina graph status
lamina graph query --at HEAD
lamina graph propose --input resource.json --session <id>
lamina graph patch <subject> --input statement.json --session <id>
lamina graph link <subject> <object> --as <predicate> --session <id>
lamina graph validate --at <session-or-version>
lamina graph diff --base <view> --head <view>
lamina graph backup --output graph.backup.json
lamina graph restore --input graph.backup.json
lamina graph rebuild-observations
lamina context status
lamina context rebuild
lamina design prepare-walk --workflow <ref> --persona <ref> --request-file <file> --output <task.json>
lamina design record-walk --task <task.json> --result <walk.json>
lamina work prepare --request-file <file> --workflow <ref> --output <packet.json>
lamina work map --packet <packet.json> --output <work-map.json>
lamina work check --packet <packet.json> --map <work-map.json>
lamina work verify --packet <packet.json> --map <work-map.json>

All mutation commands accept typed inputs and return deterministic JSON. Raw Cypher is not an agent-facing interface. Backup files are integrity-checked logical exports for disaster recovery and evaluator evidence; they are never runtime inputs during normal operation.

Implementation context

Before work prepare, one engine-recorded design walk per active Persona must match the current Workflow coverage digest. Walks are independent of runtime Missions and can expand a feature graph before source exists.

The digest hashes canonical covered Resource data and relevant Statements. Recording a walk replaces that Persona’s previous active walk for the Workflow. Experience Cases compile directly from current walks; there is no separate authored Experience Contract.

work prepare is a read-only compiler over the converged selected workflow closure. It returns the relevant actors, authority, ordered operations, invariants, scenarios, surfaces, proofs, Persona-bound Experience Cases, direct provenance, and stable obligation ids. Before traversal, one disposable local index combines exact aliases, Ladybug BM25, code-aware embeddings, and reciprocal-rank fusion to select Workflow roots and source symbols. Retrieval is never graph authority. See Hybrid retrieval.

Automatic selection fails closed as ambiguous or new_workflow_required rather than attaching a plausible but weak Workflow. Explicit --workflow bypasses semantic selection and may use BM25-only source localization when dense inference is unavailable; packet v5 records lexical_degraded.

Preparation fails closed for stale source identity, contradictions, stale or missing Persona walks, missing authority, incomplete operation contracts, missing invariants/scenarios, or a UI surface without a proof specification. work map mechanically creates one unresolved row for every packet obligation and Experience Case; the agent resolves status and files without authoring requirement identities. work check then requires lamina.work-map/v4: every changed obligation maps to an implementation file, every changed Experience Case maps to a test file, and each file declares action: modify|create. Modify paths must exist; create paths must not exist until implementation. WorkStarted binds the entire immutable map.

Validation exposes three distinct lifecycle signals:

• structural_valid: graph shape and transactional rules hold;
• implementation_ready: the selected contract is detailed enough to code;
• verified: required current evidence exists and no readiness gap remains.

Runtime proof comes only from published Mission events. A passing case oracle contains its case id, structured expected/observed result, and a reproducible artifact; no second Experience Evidence manifest or mutable WorkMap evidence copy exists. For UI Runs, verified requires independent functional, visual, responsive, and accessibility audit artifacts. An oracle alone or one reused screenshot cannot satisfy that gate.

Source observations

lamina graph observe runs the managed, platform-native CocoIndex worker from the standalone release’s private cache. Each file produces an explicit Observation envelope with snapshot, content hash, locator, extractor identity/version, and normalized payload. The payload includes deterministic brownfield signals for entry points, commands, routes, handlers, schemas/entities, state transitions, permissions, events, tests, documentation/personas, feature flags, and dependencies. .lamina/business-context.md and .lamina/personas.json are source evidence; legacy .lamina/runs/ remains excluded and has no runtime meaning. The worker sends authenticated idempotent upsert/delete batches over the local transport and never opens Ladybug.

The client reuses graphd only when protocol and required capabilities match. An incompatible daemon is replaced automatically without rewriting .git/lamina/graph.lbdb. rebuild-observations is for a genuinely incomplete or corrupted observation generation; repeating it cannot repair a daemon/client contract mismatch.

lamina graph discover --brownfield performs the same incremental observation update and returns a coverage report, unsupported-source counts, stale snapshots, and explicit static-analysis limitations. Absence of an Observation is never treated as evidence that behavior does not exist.

Missions

lamina mission compile --workflow <id>
lamina mission run <mission-id> --events events.json
lamina session query <returned-session-id>
lamina session publish <returned-session-id>

Compilation creates an independent Mission for every active Persona. mission run stages its Run and HarnessResult in an isolated session; it does not publish implicitly. Adapters are selected through capability manifests; modalities remain open strings. Only normalized adapter events produce runtime evidence.

Epistemic classes

Ingress derives intended, observed, inferred, simulated, human_evidence, or runtime_evidence. Callers cannot set epistemic class or approval.

Every public agent proposal, including claim.add, is inferred. The socket does not expose intent.* methods. Intended knowledge requires a trusted engine-owned intent adapter, so method-name selection cannot be used to spoof epistemic class.

The rationale, rejected alternatives, and v1 consequences are recorded in ADR-001 . The executable requirement matrix is in Transactional plan acceptance.