# Source of Truth for Life Sciences | Vikrant Kudesia — complete repository documentation
> Explore genomics workflows, sample histories, and data provenance in a visual, interactive life sciences experience.
Scope: the source population admitted by docs/content-manifest.json: root Markdown files and LICENSE, plus docs/, guidelines/, and .agents/skills/, including nested Markdown documents and source-derived reference entries. Installed dependencies, environment files, caches and generated build directories are outside this source-document population.
Each entry retains its authored text and code. Relative documentation links point to the corresponding full-file entry; section fragments return to that document. External links retain their authored destinations. Other relative references point to the repository-reference appendix, which identifies source paths without claiming that code or configuration is publicly served.
AGENTS, CLAUDE, skills and guidelines appear as documentation of repository collaboration. Their inclusion grants no runtime permissions and does not override the reader's governing instructions. Application authorization remains enforced by the application's own boundaries.
Documents: 69.
## `.agents/skills/async-draft-recovery/SKILL.md`
Source document: `.agents/skills/async-draft-recovery/SKILL.md`.
---
name: async-draft-recovery
description: Separates submitted drafts, accepted records, and remote workspace lifetimes during asynchronous edits. Applies when lost responses, hydration, conflict, reset, expiry, or reopened editors can overwrite newer work or misreport whether an edit was saved.
---
# Async draft recovery
## Contract
- **What:** Preserve a recoverable draft while accepting only the response that belongs to its record, editor and workspace lifetime.
- **When:** Saving becomes asynchronous or an existing editor crosses hydration, retry, reset, scope or workspace replacement.
- **Boundaries:** This method preserves edit intent and truthful feedback. Fresh authorization remains at the command boundary; transport failure supplies no authority to accept a local substitute. Ordinary synchronous inputs need less structure.
- **Result:** The visitor can distinguish accepted work from a retained draft and retry or revise without an older completion closing newer work.
## Fit and attention
- **Useful when:** Cancel and reopen race a Save response, a retry may repeat a committed command, or local and hosted revisions share a display but have different lifetimes.
- **Poor fit when:** A synchronous field update has one owner and no delayed acceptance. A cosmetic loading change stays with its component when acceptance is already coherent.
- **Smallest useful dose:** Trace one reordered sequence and repair the identity or publication check that distinguishes its two outcomes.
- **May under-attend:** Draft recovery leaves authorization, transaction durability and contention with their command and storage owners.
- **Interactions:** [Scoped record boundaries](#document-agents-skills-scoped-record-boundaries-skill-md-21058871cd20) owns current authority; this skill owns the editor and response relationship.
## Inputs, defaults and output
Read the editor, accepted-state owner, transport outcomes and server receipt contract. Identify values that actually change independently:
| Identity | Question it answers |
| --- | --- |
| Record ID and revision | Which accepted record did the visitor edit? |
| Editor instance or generation | Which open draft may receive completion feedback? |
| Workspace identity and generation | Which namespace owns these revisions and retries? |
| Read sequence | Which hydration request is current within that namespace? |
| Scope generation | Does the action still belong to the current permission scenario? |
| Normalized command identity | Is this the same submitted intent or a newly edited command? |
Use the identities needed by the actual workflow. Keep the draft while acceptance is uncertain. If the server lacks a receipt contract, establish its retry behavior before describing a retry as safe. The output is a bounded ownership repair and an observation of both the accepted record and editor; a new state framework is optional.
## Rules
### Rule: Track the identities that can change independently
Record revision, editor instance, workspace identity, request order and scope generation answer different questions. Reopening the same record creates a new editor lifetime even when its record ID is unchanged. A new hosted workspace creates a new revision namespace even when its first revision is lower than a local record's revision.
### Rule: Hydrate before deciding against accepted state
Resolve the current persistence mode and accepted snapshot before submitting. An explicit local mode permits local acceptance. Outage, expiry, denial and absent installation retain distinct outcomes. Replacing a workspace resets its projection and retry identities before merging; within one workspace, older revisions cannot replace newer accepted records.
### Rule: An uncertain response preserves exact retry identity
A lost response does not establish that a command failed to commit. Retain the identity of the same normalized intent and expected revision for retry. Changed intent gets a new identity. Server receipts own duplicate acceptance; client identity alone provides no exactly-once guarantee. Conflict refreshes accepted state while keeping the draft available for review.
### Rule: Completion belongs to the submitted editor
Either freeze submitted fields while a save runs, with Cancel available, or explicitly separate subsequent editing from the submitted snapshot. Guard close, success notices and draft replacement by the submitting editor generation. Cancelling a view withdraws its UI effects; it does not assert cancellation of an already accepted server command.
### Rule: Recovery stays explicit
Expiry and reset invalidate older hydration and mutation responses. Starting another workspace is a new action, not silent replay of the old save. Accepted history describes what was confirmed; a timeout message keeps the draft and offers a truthful retry.
## Operating sequence
1. **Reconstruct:** Write submit → close/reopen → response, or hydrate → reset → late snapshot. Record the initial accepted revision and visible draft separately.
2. **Assign:** Name the owners of accepted data, submission identity, editor and notice. Find the await or callback where each can become stale.
3. **Discriminate:** Decide whether a late result may update accepted state, editor state, both or neither. A confirmed result can remain useful after its editor closes, subject to current workspace and scope.
4. **Repair:** Add the missing boundary at that owner. Reuse existing normalization, permission preparation and server receipts rather than duplicating them in the component.
5. **Observe:** Hold one response, make the competing change, then release it. Inspect accepted text/revision, the current draft and notice independently. For namespace replacement, use a lower incoming revision to distinguish it from ordinary monotonic merging.
6. **Return:** Name the repaired sequence and its retry, refresh or restart action. Source review establishes the owner path; an executed test establishes the reordered case it asserts.
## Local receivers
- [Source workspace owner](#source-78bb60083fcc): hydration, workspace generations, monotonic merge and retry identity.
- [Source editor](#source-1a536c6fc0b6) and [Sources receiver](#source-6d1697c4ea00): submitted fields, retained draft and editor-generation guards.
- [Workspace store](#source-8419754623cf): transactional receipts and revision acceptance.
- [Owner observations](#source-e0f8fa0df343), [browser journeys](#source-11cee35cf6d2), and [workspace contract](#document-docs-visitor-workspaces-md-49294a63218a): actual recovery routes and coverage.
The owner tests cover explicit LOCAL mode, ambiguous retry, stale hydration, conflict, scope changes and first hosted hydration below the local revision. The held-response browser case asserts frozen submitted fields, Cancel while pending, blocked reopening during that request, and reopening with accepted text after settlement. It requires the separate disposable database route. Guarding a newer editor against an older completion remains a design invariant supported by the editor-generation source checks; that browser case does not exercise two overlapping editor instances. [SQL workspace cases](#source-655391fe8176) own transaction and receipt observations. These links identify existing assertions, not a claim that they ran during every skill use. Use the [local writing guide](#document-agents-skills-declarative-skill-authoring-references-writing-and-evidence-md-b2b19351a072) when recovery messages or substantial handback prose change.
## Authored routing example
- **Given:** Local metadata has revision 1 and the first hosted snapshot has revision 0 in a newly identified workspace.
- **When:** Hydration receives that snapshot.
- **Then:** The owner installs the hosted namespace before applying its revisions. A revision-only comparison would incorrectly keep local work as though it were hosted. The draft remains available for an explicit save against the new accepted state.
This authored example explains the discriminator; the named first-hosted-hydration owner test supplies the executable assertion for this repository.
## Recovery and re-entry
When acceptance remains uncertain, preserve the draft and retry identity, then use the existing status/receipt route. When a workspace ends, show that state and let the visitor start another explicitly. If ownership remains unresolved, retain the draft and route the missing acceptance decision to the command owner. An additional spinner can describe waiting; identity checks determine which result may publish.
## Completion
Complete when the current editor, accepted record and feedback agree through the relevant reordering, and the visitor retains one clear recovery action. Re-enter when a persistence mode, editor lifetime or receipt policy changes that relationship. Ordinary fields keep their existing simpler ownership until an independent lifetime requires more structure.
## `.agents/skills/declarative-skill-authoring/SKILL.md`
Source document: `.agents/skills/declarative-skill-authoring/SKILL.md`.
---
name: declarative-skill-authoring
description: Authors and revises self-contained repository skills with precise routing, consequential rules and observable completion. Applies when repeated collaboration reveals a reusable method, a skill misroutes work, or a clone needs guidance that currently depends on conversation context.
---
# Declarative skill authoring
## Contract
- **What:** Turn an evidenced collaboration method into instructions another collaborator can select, apply, check and revise.
- **When:** A recurring decision needs more context than standing repository guidance supplies, or an existing skill fails to transfer to its next receiving task.
- **Boundaries:** User intent, repository policy, current source and granted tools retain authority. A skill supplies a method; activation grants neither publication permission nor proof of effectiveness. Direct reasoning remains the complete route for a one-off task.
- **Result:** A conventional `SKILL.md` and only the supporting resources needed to make its fit, actions, evidence and recovery legible in an independent clone.
## Fit and attention
- **Useful when:** A repeated ownership mistake, missing decision discriminator or recovery sequence can be captured as a transferable method.
- **Poor fit when:** The proposed skill repeats AGENTS, records one Issue's status, describes a single bug fix, or replaces one adequate command with a framework.
- **Smallest useful dose:** Revise the existing owner; create a new skill only when it owns a distinct receiving result.
- **Foregrounds:** Routing, authority, discriminating decisions, useful context and cold-reader completion.
- **May under-attend:** A coherent instruction document can still produce weak decisions. Receiving-task observations establish utility separately from structural validity.
- **Interactions:** The [test-suite skill](#document-agents-skills-test-suite-composition-skill-md-412c39ca5e33) selects executable evidence. The [runbook index](#document-docs-runbooks-readme-md-39a19900e08a) holds settled ordered routes. Issues own active scope and acceptance.
- **Rest or release when:** The reader can finish the bounded job, a simpler standing instruction absorbs it, or the receiving capability retires.
## Inputs, defaults and output
Read the current request, nearest README, applicable source, existing skill catalog in [AGENTS](#document-agents-md-a54ff182c7e8), and the observation that prompted authoring. Name the expected receiver and a plausible near miss. A remembered failure is a hypothesis until current source or a receiving observation establishes it.
When evidence is incomplete, write a working method with the open question and the next discriminating observation. Existing behavior continues through its accepted owner. A missing account or tool capability becomes a named handback, rather than a skill dependency that a clone cannot fulfill.
The output is one skill directory under `.agents/skills/`, with `name` and third-person `description` frontmatter. Keep shared instructions in `SKILL.md`; link substantial conditional material one level below it. Load [the authoring pattern](#document-agents-skills-declarative-skill-authoring-references-authoring-pattern-md-760704bbbeaf) when creating or structurally revising a skill. Load [the writing guide](#document-agents-skills-declarative-skill-authoring-references-writing-and-evidence-md-b2b19351a072) for material instruction or runbook prose.
## Rules
### Rule: Capability and trigger govern selection
The description names the method's result and the conditions that make it useful. Names identify the job, rather than a person, competency claim or task number. Include a poor-fit boundary when it prevents realistic misrouting. A broad topic such as React or security alone provides too little selection context.
### Rule: Contracts precede mechanics
State What, When, Boundaries and Result before the operating sequence. Separate an invariant from a convenient local implementation. A request-generation guard may be essential; its current variable name belongs in a source receiver link. Commands come from current package scripts and configurations rather than remembered conventions.
### Rule: Depth follows the decision
Include the inputs, default behavior, missing-input response, material output and recovery needed to act. Explain a non-obvious tradeoff where the wrong choice would change behavior. A longer skill earns its length through distinct decisions; repeated cautions and generic quality aspirations add reading cost without adding capability.
### Rule: Local dependencies travel with the clone
Every required local link resolves from the skill. A public source may supply provenance or optional deeper research; the operative method and required writing instructions remain available here. Replace workstation paths, private workspace locators and conversation-specific instructions with local owners and explicit entry conditions. Preserve source credit through a bounded public provenance link.
### Rule: Rules retain agency and exact boundaries
Name the collaborator, test runner, command owner or receiving view that acts. Lead with the desired state, classify each negation, and keep a necessary exclusion beside its permitted route. Preserve test assertions, legal/privacy boundaries, exact quotations and uncertainty. The writing guide provides the complete local method and its evidence limits.
### Rule: Examples clarify a branch
Retain the smallest scenario set that changes a decision: an ordinary path, consequential boundary or near miss. Each scenario names initial state, event, observable result and recovery when needed. Authored Given/When/Then prose expresses intent. Link an executable test explicitly when one supplies observation; the prose itself remains instruction evidence.
### Rule: Reuse retains ownership
A portable skill owns the general method; this repository owns its local adaptation and source map. A companion runbook sequences an already understood route. Supporting skills own distinct results and keep their own completion conditions. Avoid requiring another entire skill merely to retrieve one local fact.
### Rule: Helpers follow repeated mechanics
An instruction-only skill is a complete first version. Add a script when repeated, fragile work demonstrates a useful deterministic boundary. Exercise that script's meaningful success and refusal paths. Validation of frontmatter or links establishes structure; it leaves the skill's decision quality open.
### Rule: Outside evidence reopens the method
Human correction, source changes, a cold-reader failure or an independently grounded source can revise the contract. Reuse counts and self-authored examples describe activity. They establish neither correctness nor universal transfer. Narrow, combine or retire guidance when its receiving job changes.
## Operating sequence
1. **Locate:** Identify the current outcome and existing instruction owner. Decide whether a direct answer, skill revision, new skill or runbook best serves it.
2. **Bind:** Name the receiver, active authority, source owners and smallest useful intervention. Retain unavailable evidence as an explicit open item.
3. **Write:** Draft metadata and contract, then the decisions and actions that change the outcome. Link conditional context at its load point.
4. **Review language:** Use the writing guide on headings, tables, examples and code comments as well as prose. Preserve supported actors, claim strength and boundaries.
5. **Check structure:** Verify frontmatter, local links, real commands and source receivers. Read the skill from an independent-clone vantage.
6. **Exercise:** Give a fresh reader a realistic task, the skill and minimum raw source. Keep the expected answer out of the task. Add one near miss when routing is uncertain. Compare its actual decisions with source and acceptance.
7. **Settle:** Fix decision-changing friction, update AGENTS discovery and hand back one concise review record. State what was exercised, what remains unobserved, and the event that would reopen the skill.
## Consequential examples
### A repeated local number looks like a universal rule
- **Given:** The current showcase bounds an API resource to a small process-local limit.
- **When:** The author captures its admission-lifetime method.
- **Then:** The skill preserves ownership and cleanup rules, links the configured limit, and lets the receiving workload determine its value. A different deployment reopens capacity selection while preserving the lifetime invariant.
### A simple caption edit reaches the skill catalog
- **Given:** One caption needs a direct wording correction and existing writing guidance covers it.
- **When:** The collaborator considers adding a skill.
- **Then:** The collaborator makes the authorized edit and checks its meaning directly. A new skill waits for a distinct recurring method or observed gap.
## Recovery and completion
If an exercise misroutes a task, revise the smallest trigger or decision that caused it and repeat that case. Keep a disputed behavior with its current source owner until evidence or user direction resolves it. An unsuccessful experiment can settle with a narrower skill or a documented direct-reasoning route.
Complete when a fresh reader can identify fit, execute within authority, interpret evidence and recover using this repository alone. Record independent exercise separately from runtime tests. Reopen on a material source, environment or receiving-task change.
## Provenance
Adapted from the public [exemplars skill-authoring contract](https://github.com/driftframestudios/human-ai-systems-exemplars/blob/main/.agents/skills/declarative-skill-authoring/SKILL.md). This local contract and its references supply the complete receiving method; upstream research and future revisions inform review rather than silently changing repository instructions.
## `.agents/skills/declarative-skill-authoring/references/authoring-pattern.md`
Source document: `.agents/skills/declarative-skill-authoring/references/authoring-pattern.md`.
# Authoring pattern
Use this pattern during creation or structural revision. Retain sections that change a reader's decisions; the outline is a writing aid rather than a schema requiring identical length across skills.
```markdown
---
name: capability-name
description: . Applies when .
---
# Capability name
## Contract
- **What:**
- **When:**
- **Boundaries:**
- **Result:**
## Fit and attention
## Inputs, defaults and output
## Rules
### Rule:
## Operating sequence
## Conditional context
## Recovery and completion
```
Examples belong beside the decision they clarify or in a short scenario section. Write Given/When/Then only when those branches help interpretation. Mark intended examples separately from executed cases. Cite current source when a source-specific rule matters; keep long receiver inventories in a conditional reference when they compete with the core procedure.
## Runbook companion
A runbook orders a known multi-phase route across current owners. Its short header carries `title`, semantic `version`, `status`, `audience`, `source_band` and singular `task_type`. Use `working`, `exercised`, `stable` or `retired` to describe observed maturity. One completed exercise can establish `exercised`; repeated settled use supports `stable`.
Name the receiving state, entry conditions, authorized action mode, ordered phases, checkpoint meaning, recovery and stop condition. An unavailable entry condition receives a safe next action. Issues retain current scope and acceptance, while user instructions retain authority. A public-possible return includes the changed artifact, normalized evidence, coverage and next receiver; raw logs, credentials and private locators remain with their existing protected owner.
The [runbook index](#document-docs-runbooks-readme-md-39a19900e08a) shows current local examples. A first authoring exercise checks whether another reader can enter and finish from the runbook and linked source, rather than treating the header as proof of readiness.
## Proportionate review
- **Routing:** A realistic task selects the skill, and a plausible near miss selects direct work or a different owner.
- **Structure:** Metadata names a capability; links resolve; all required context travels with a clone.
- **Action:** The reader identifies actual actors, current source, authority and a bounded output.
- **Evidence:** An authored example, executable test, review and hosted observation retain distinct meaning.
- **Recovery:** A consequential failure preserves useful state and identifies a next action.
Use an independent reader for complex methods when available. Supply the task and raw evidence without the intended answer. Keep the exercise within existing authorization and record its actual result, including any remaining gap. A runtime suite becomes relevant only when executable behavior or its check owner changes.
## `.agents/skills/declarative-skill-authoring/references/writing-and-evidence.md`
Source document: `.agents/skills/declarative-skill-authoring/references/writing-and-evidence.md`.
# Writing instructions another collaborator can use
This local guide applies to skills, runbooks and their receiving summaries. It combines the exemplars' [supportive-change register](https://github.com/driftframestudios/human-ai-systems-exemplars/blob/main/.agents/skills/supportive-change-writing/SKILL.md) and [agency-and-action method](https://github.com/driftframestudios/human-ai-systems-exemplars/blob/main/.agents/skills/agency-and-action-writing/SKILL.md). Those public contracts preserve the deeper source lineage; the operative method is included here for independent clones.
## Lead with a useful state
Name what the reader can create or verify. Use concrete actors, verbs and objects when supported: “The command owner resolves current consent before accepting a restore.” Professional distance, an impersonal construction or a precise abstraction remain appropriate when the actor is unknown, protected or irrelevant. Preserve contribution boundaries; participation and ownership make different claims.
Give each paragraph one job. Connect the action to its material consequence, such as retaining a draft or releasing a database connection. Warm, direct language treats strain as a condition of the workflow and gives the reader a workable next move.
## Classify negation before revision
| Language function | Treatment | Receiving check |
| --- | --- | --- |
| Generative instruction or tone goal | State the desired behavior directly when it preserves meaning. | Does a representative receiving task produce the intended behavior? |
| Safety, privacy, compatibility or authority boundary | Preserve the exact exclusion beside its permitted route. | Can the reader identify the boundary and useful continuation together? |
| Definition or evidence limit | Preserve the qualifier beside the supported claim. | Does the revised claim retain the original scope? |
| Test assertion or absent-state check | Preserve executable semantics and name the invariant. | Does the same plausible fault still fail? |
| Source title, quotation, governed label or code identifier | Retain exact source fidelity. | Does the carrier still match its source? |
This is an authoring heuristic, not a claim that every model handles negation alike. Prompt following, training-time learning, retrieval and multilingual interpretation are different observations. Test a consequential rewrite in its actual receiver. Ordinary prose edits generally need a proportionate editorial review.
Keep a boundary in the same sentence, bullet or table row as the action it governs so partial context preserves their relationship. A positive operating target often reduces inference; a hard exclusion still deserves explicit language.
## Examples that retain meaning
| Source problem | Useful revision | Preserved boundary |
| --- | --- | --- |
| “Do not lose edits when resizing.” | “The shared accepted-state owner retains edits while the receiving layout remounts.” | The layout reads the existing owner; it cannot replace accepted work with defaults. |
| “No tests failed,” after runner output confirms 15 executed browser passes and no database execution. | “The selected 15 browser journeys passed. Database behavior remains unobserved in this run.” | A skipped or absent assertion establishes no adjacent behavior claim. With only a zero-failure count, report that count and inspect execution before claiming a pass. |
| “Don't print secrets.” | “The summary carries normalized results. Credentials and raw request headers remain with the protected runtime owner.” | Secret material never enters the published summary. |
| “The fix was made.” | “The command owner now rechecks scope when the visitor submits the edit.” | The claim covers that owner and acceptance event. |
## Review and return
1. Identify the audience, actor, action, affected object and supported consequence.
2. Revise only what the evidence establishes; keep missing facts as open questions with a receiving owner.
3. Classify retained negations and pair material exclusions with an affirmative continuation.
4. Distinguish verified source behavior, observed tests, supported inference, proposal and authored scenario.
5. Check headings, bullets, table cells, examples and code comments as well as paragraphs.
6. Return the changed state, what the observation establishes, its coverage boundary and the next revisable move.
One receiving record is enough. A PR body can carry the decision and evidence; linked runbooks carry the repeatable procedure. Reopen wording when an actual reader, source change or receiving result shows that it changes the wrong behavior.
## `.agents/skills/publication-boundary/SKILL.md`
Source document: `.agents/skills/publication-boundary/SKILL.md`.
---
name: publication-boundary
description: Inspects named source and release scopes with a verified scanner, fresh synthetic canary and sanitized receipt. Applies before a commit, clean snapshot, documentation bundle or deployment archive crosses a publication boundary.
---
# Publication boundary
## Contract
- **What:** A bounded credential-shaped material observation, alongside a distinct reading of embedded metadata and publication intent.
- **When:** Source, an exact proposed index, documentation or an archive is preparing for another repository, release or public audience.
- **Boundaries:** User authorization supplies publication and mutation authority. This method identifies candidates; the credential owner determines validity and any rotation. Scanning keeps provider validation disabled. Repository visibility, rights, consent and historical cleanup retain their existing owners.
- **Result:** The selected detector path proves detection and masking, each named scope returns zero unresolved matches or a private recovery route, and the receipt states its coverage.
## Rules
### Rule: The receiving source owns its observation
Read the local [runbook](#document-docs-runbooks-publication-scan-md-2fd2d22ef3bb), pinned [installer](#source-c19fa97b0565), [scanner](#source-2f059532cade) and [configuration](#source-5c695e582d60). Another repository's receipt supplies lineage. The assembled receiving source supplies its own observation. Commands work without another checkout or private account.
### Rule: Every invocation proves the detector first
The scanner generates a new non-issued provider-shaped value in memory and requires its finding exit, parsed masked report and sanitized return. A failed canary stops acceptance of a subsequent clean result. Installation verifies the official archive checksum and records executable identity; each scan verifies that receipt, current executable bytes and reported version.
### Rule: Scope determines the claim
Tracked working files, exact index blobs, a committed export, a changed-commit comparison, local-ref textual history and a named artifact are separate scopes. A changed-source pass leaves unchanged files and earlier history unobserved. A quiet or skipped CI job records selection, not inspected behavior. Source and configuration changes reopen their affected observations.
### Rule: Findings remain private until classified
Normal output carries scope, count, rule and safe identity. Candidate values, raw diagnostics, paths, headers, filenames and commit messages stay outside published logs and receipts. A plausible credential pauses the affected handoff and routes to its owner; rotation precedes cleanup. A verified non-issued fixture earns one exact path/rule/value exception and an executable boundary check. Broad baselines and inline allowances do not substitute for classification.
### Rule: Metadata and audience need their own reading
Inspect publication images for EXIF/XMP/IPTC location, device serial, author, capture time, workstation path and tool residue. Inspect archive entries and generated derivatives, preserving intentional color profiles and attribution. A credential scan does not establish metadata absence, visible-content suitability, rights or consent. Current binary metadata and historical binary objects are different observations.
## Sequence and completion
1. Confirm source revision, existing changes, intended receiving event and authority. Preserve unrelated work.
2. Select the smallest scope that can change the decision; use the runbook's deeper release route when a complete snapshot leaves the repository.
3. Verify the installer and configuration, run the fresh-canary scope, and read its sanitized outcome.
4. Classify candidates privately or receive the clean bounded result. Inspect relevant binary metadata separately.
5. Return one receiving record with source/configuration identity, executed scope, outcome, limitation and next receiver. Re-run after assembly in another repository.
Completion means every requested scope has a clean receipt or named private response owner. It grants neither publication approval nor universal secret absence. Re-enter when the source, engine, exceptions, artifact generator, audience or receiving assembly changes.
This method adapts the public [exemplars secret-boundary contract](https://github.com/driftframestudios/human-ai-systems-exemplars/blob/main/.agents/skills/secret-boundary-inspection/SKILL.md). The local implementation and tests are the operative owners.
## `.agents/skills/resource-admission-lifetimes/SKILL.md`
Source document: `.agents/skills/resource-admission-lifetimes/SKILL.md`.
---
name: resource-admission-lifetimes
description: Aligns request admission with the lifetime of unfinished handlers and owned resources. Applies when deadlines, aborts, plugin wrapping, or shared API routes can report completion before connections or work actually settle.
---
# Resource admission lifetimes
## Contract
- **What:** Bound active work using its real completion boundary while returning a timely, recoverable response.
- **When:** A request deadline, cancellation path, connection wrapper or API route changes how work is admitted and released.
- **Boundaries:** This is process-local resource ownership, not a distributed quota, identity system or general performance audit. Choose a limit from the receiving workload and existing owner; the showcase's current number is not a universal default.
- **Result:** Excess work is refused before expensive acquisition, and capacity returns only when the admitted handler and its owned cleanup settle.
## Fit and attention
- **Useful when:** A timeout response precedes query completion, routes use separate counters over one resource, or plugin order obscures the lifetime being counted.
- **Poor fit when:** The only issue is a slow pure calculation, idle animation or upstream account quota. Inspect that owner directly before adding admission machinery.
- **Smallest useful dose:** Hold one handler past its response deadline, then observe refusal before release and acceptance after cleanup.
- **May under-attend:** A correct cap bounds admitted work. Throughput, fairness, queueing policy and the appropriate cap value require their own workload evidence.
- **Interactions:** [Async draft recovery](#document-agents-skills-async-draft-recovery-skill-md-af57d63e7cb0) owns a write whose commit may outlive its response. A capacity release alone leaves commit status unresolved.
## Inputs, defaults and output
Read the installed wrappers, their construction order, the acquisition/close owner and current limits. Capture these boundaries for one route:
| Boundary | Required question |
| --- | --- |
| Admission | Which counter is shared, and what is refused before acquisition? |
| Acquisition | Can opening finish after abort? Who disposes that late resource? |
| Work | Which promise represents the actual handler or driver operation? |
| Response | Which deadline can return before that promise settles? |
| Cleanup | Which awaited path closes connections, listeners and transport? |
| Release | Which `finally` returns capacity after cleanup? |
Default to the existing bounded refusal and retry route. Preserve the accepted limit unless the task supplies a reason to change it. If driver cancellation is uncertain, retain the slot through actual completion and name that limitation. The output is an inspectable lifetime trace, a focused repair when needed, and an observation that distinguishes response completion from resource release.
## Rules
### Rule: Separate response time from work lifetime
A deadline can produce a response while the handler continues. Count that unfinished work until its own `finally` completes. Releasing a slot when the timeout response wins allows repeated timeouts to accumulate more underlying work than the cap describes.
### Rule: Draw the actual wrapper order
Plugin registration order may construct wrappers in reverse execution order. Trace request entry, admission, resource acquisition, deadline response and cleanup separately. Put admission around the handler lifetime that includes storage cleanup, with the deadline able to return independently. Confirm composition through the installed wrapper's behavior rather than relying on a comment or array position.
### Rule: A shared resource earns a shared admission owner
Routes drawing on the same bounded process capacity receive the same counter instance. An overflow response starts no repository or workspace work. Required error headers and a short retry instruction belong to that outer response; resolver-level decoration may be bypassed by a deadline or admission refusal.
### Rule: Abort reaches the resource that can release it
An abort signal and a stopped UI do not prove that a driver command or socket settled. Account for cancellation while opening, while querying and while closing. Own an idempotent cleanup path that disposes late-opened resources and removes listeners. Preserve the original failure while cleanup releases the underlying capacity.
### Rule: Reads and uncertain writes retain different recovery
A stopped read can return unavailability after disposal. A write may have committed before its response or connection failed. Keep retry identity and receipts with the write owner. A capacity release authorizes another request; it does not authorize replaying an uncertain mutation under a new identity.
## Operating sequence
1. **Locate:** Choose the actual route and shared resource. Follow the configured plugin/library far enough to establish wrapper execution order.
2. **Trace:** Write entry → admission → acquisition → work → response → cleanup → release, allowing response to occur earlier. Mark the promise or callback owning each event.
3. **Constrain:** Confirm overflow exits before resource creation and related routes use the intended instance. Inspect the outer refusal's status, cache headers and retry message.
4. **Exercise:** Hold the first handler beyond its deadline. Attempt another request while work is held; release cleanup; attempt again. This distinguishes a work cap from a response-only cap.
5. **Expand where touched:** Add a thrown handler, late connection or shared-route case when the repair changes that branch. Inspect a throwing cleanup separately when the driver supports that failure. Use driver integration for socket/transaction claims.
6. **Receive:** Report the lifetime bounded and cleanup observed. A held-handler observation leaves distributed capacity and load performance unmeasured.
## Local receivers
- [Request admission](#source-594a5cb2c755): shared unfinished-handler counter and overflow response.
- [Read API](#source-ff9c0f82685e), [workspace API](#source-fde577d33b62), and [HTTP composition](#source-16966778dca8): actual wrappers and shared instance.
- [Read connection scope](#source-1a24ec4051db) and [workspace transaction connection](#source-26e2e6b3ba2a): distinct owned cleanup paths.
- [Admission observations](#source-195769eedd8c): executable delayed-handler, failure and shared-route cases. [GraphQL contract](#document-docs-graphql-read-api-md-03dad145256f) owns current operational bounds.
[Connection tests](#source-10dec939d79f) own the covered lazy-open and read-cancellation cases. [Storage unit cases](#source-b9ef7bef8a5f) inspect write/read transaction cleanup through a controlled adapter; [SQL cases](#source-655391fe8176) supply a separate engine observation. Choose the receiving layer matching the claim. These links identify available checks; record executed results only when that route runs. Use the [local writing guide](#document-agents-skills-declarative-skill-authoring-references-writing-and-evidence-md-b2b19351a072) when refusal or recovery prose changes.
## Authored routing example
- **Given:** One admitted handler remains blocked after its deadline response and the process cap is one.
- **When:** A request reaches the other route sharing that capacity owner.
- **Then:** It receives the busy response before opening storage. After the original handler's cleanup settles, a retry can enter.
This authored example names the discriminator. The admission tests supply the executable held-handler observation; a browser timeout alone cannot establish it.
## Recovery and re-entry
If a driver cannot cancel work, retain the slot until completion and offer the existing retry response. If a wrapper upgrade changes composition, return to the lifecycle trace and observe that installed composition before changing limits. Keep incomplete cleanup visible as an unresolved owner question. A move to multiple processes reopens capacity ownership because a local counter bounds only its own process.
## Completion
Complete when admission, response and cleanup have distinct verified owners, the relevant refusal acquires no expensive resource, and a retry succeeds after release. Re-enter when a route, driver, wrapper or deployment topology changes the shared lifetime.
## `.agents/skills/responsive-intent-handoff/SKILL.md`
Source document: `.agents/skills/responsive-intent-handoff/SKILL.md`.
---
name: responsive-intent-handoff
description: Preserves scene intent across responsive receivers, deferred loading, and guided playback. Applies when remounts, late readiness, camera motion, or manual takeover can replace the visitor's current exploration.
---
# Responsive intent handoff
## Contract
- **What:** Separate retained exploration intent from the lifetime of its current renderer and automatic presentation effects.
- **When:** A viewport change, lazy scene, guided step, or camera transition can replay an old selection or lose a current one.
- **Boundaries:** This method owns presentation continuity. Accepted edits and permission scope stay with their existing owners. A spacing-only change usually needs direct layout work instead.
- **Result:** The receiving layout shows the current permitted scene and selection, while obsolete work relinquishes control.
## Fit and attention
- **Useful when:** Resizing replaces a renderer, a guide waits for a lazy scene, or direct input competes with pending navigation, scrolling or camera motion.
- **Poor fit when:** A panel only needs spacing or width changes and retains the same owner. An accepted-record conflict belongs to its data workflow even when resizing exposes it.
- **Smallest useful dose:** Trace one retained selection through a receiver change and one competing manual action.
- **May under-attend:** State continuity can be correct while the scene remains visually crowded or offscreen. A settled viewport observation supplies that separate layout evidence.
- **Interactions:** [Scoped record boundaries](#document-agents-skills-scoped-record-boundaries-skill-md-21058871cd20) determines which selection remains permitted; [async draft recovery](#document-agents-skills-async-draft-recovery-skill-md-af57d63e7cb0) owns pending saves independently of presentation.
## Inputs, defaults and output
Read the parent state owner, responsive/deferred receiver, effect cleanup and relevant scene contract. Classify each value before moving it:
| State or effect | Default lifetime |
| --- | --- |
| Selected scene, well/result, intended history mode | Shared exploration intent across compatible receivers |
| Local rail visibility, DOM measurements, pointer capture | Current renderer, unless the task explicitly requires persistence |
| Frame handle, timer, scroll callback | Effect instance with explicit cancellation |
| Guide step and readiness | One identified scene request |
| Accepted edit or recovery deadline | Existing accepted-state owner above renderer replacement |
Define what “ready” means for this receiver: current data, a settled camera, an available companion panel, or a stated combination. Prefer existing selection and scope owners. If a receiver cannot resolve a selection yet, preserve the intent and show the existing pending/unavailable state rather than manufacturing a replacement. The output is a bounded ownership repair, a current/obsolete event trace and the fitting state or visible-scene observation.
## Rules
### Rule: Classify before lifting state
Scene choice, selected well/result and intended history mode can outlive a renderer. DOM measurements, open local rails, pointer capture and animation handles belong to that renderer. Accepted recovery deadlines belong to the accepted-state owner; remounting a view resumes the remaining work rather than restarting its duration. Move each value only as high as its required lifetime.
### Rule: Readiness belongs to a request and an observable receiver
A scene request identifies one navigation intent. Data arrival and camera settlement may both be required before its reading interval starts. A mounted component or elapsed delay alone establishes neither. A terminal unavailable or denied result hands control back through the existing receiver.
### Rule: Cancellation changes ownership, not only playback
Pause, dismissal, a newer request and direct interaction invalidate pending automatic selection and scrolling. Include wheel zoom and queued resize frames when they control the scene. Every delayed callback checks current ownership before publishing. A late acknowledgement can describe readiness without restarting playback. An explicit reopen issues a fresh request; its recovery control remains reachable on compact screens.
### Rule: Preserve the receiving surface
A responsive handoff may replace composition while keeping selected identity and accepted state. Scene preparation routes through existing navigation and scope owners. It does not manufacture a default result over an explicit selection. Inspect the actual scene in the smallest supported orientation: guidance can be readable while accidentally pushing its subject outside the visible area.
### Rule: Motion preference changes delivery, not intent
Reduced motion may settle immediately and keep guidance stepwise; it still reaches the selected scene and its readiness outcome. A restored view resumes an accepted recovery deadline from its remaining time. Cosmetic camera motion and accepted operational time retain different owners.
## Operating sequence
1. **Reconstruct:** Start with the current selection and name the event that replaces or defers its renderer. Separate retained values from renderer-local handles.
2. **Bind:** Give the automatic request an identity and identify its readiness sources. Decide which owner can authorize selection, camera motion, scrolling and a reading timer.
3. **Trace takeover:** Follow pointer, wheel, keyboard, dismissal and newer-request paths that actually control the scene. Name where each invalidates pending automatic effects; pausing a timer alone leaves other callbacks live.
4. **Repair locally:** Place retained intent above the relevant remount boundary. Guard delayed callbacks at publication and cancel owned frames/listeners at cleanup. Keep accepted records in their existing owner.
5. **Observe the discriminator:** Delay readiness, make the competing selection and release the delay. Check the selected identity and playback separately. A responsive round trip must retain explicit intent; an explicit reopen must issue fresh authority.
6. **Inspect the receiver:** At the affected portrait/landscape or compact/wide boundary, verify that the selected scene and recovery control remain visible. Use controlled time for phase assertions and settled visual review for spatial claims.
7. **Return:** Name the retained intent, withdrawn effect and observed outcome. A reducer test establishes state transitions; browser and viewport observations establish their receiving UI behavior.
## Local receivers
- [ExplorationProvider](#source-5fb8b7d40fe1): retained scene and selection intent.
- [GuideProvider](#source-a2e1157418a8) and [guide receivers](#source-539e586bbae8): request identity, takeover and scoped readiness.
- [Scene transition owner](#source-fb0c18918ba2): cancellable frames, delays and motion.
- [Responsive journeys](#source-21afea068eb6) and [guide journeys](#source-9df344b56900): executable receiving observations. The [mobile contract](#document-docs-mobile-showcase-md-a1c532f6fcd0) owns composition details.
[Responsive exploration journeys](#source-d9c338cfe457) cover Plate/Board intent across both directions of the breakpoint. [Guide reducer tests](#source-9c1afdaf9e5e) cover stale acknowledgement, pause, replay and completion; the guide browser cases exercise wheel takeover, late history after exit and compact scene receiving. [Scene transition tests](#source-ed6e89432ca6) own cancellable motion mechanics. These links identify assertions to inspect or execute, rather than a standing pass claim. Use the [local writing guide](#document-agents-skills-declarative-skill-authoring-references-writing-and-evidence-md-b2b19351a072) when readiness messages or substantial handback prose change.
## Authored routing example
- **Given:** A guide requests history while its scene and data load.
- **When:** The visitor selects another scene before readiness arrives.
- **Then:** The old read may finish its own lifecycle, while current exploration retains control. That completion cannot reselect history or restart playback. An explicit reopen issues a fresh request and remains reachable on a compact screen.
This authored example explains the ownership branch. The guide's late-history and takeover tests carry the implemented assertions; the prose itself supplies no runtime result.
## Recovery and re-entry
If preparation is interrupted, keep the visitor's current scene and offer the existing explicit reopen control. If scoped data is denied or unavailable, let its receiver show the reason and recovery route; automatic playback pauses there. If a motion or resize callback survives cleanup, identify its owner and withdraw that authority before adding another delay.
Re-enter when a new renderer, deferred companion, automatic effect or breakpoint changes who can publish selection. A layout-only adjustment can return to direct visual work once continuity is already established.
## Completion
Complete when the current permitted selection reaches its new renderer, obsolete callbacks leave it intact, manual exploration keeps control and the relevant receiver remains visibly usable. Record the tested transition and viewport separately so each claim retains its evidence.
## `.agents/skills/scoped-record-boundaries/SKILL.md`
Source document: `.agents/skills/scoped-record-boundaries/SKILL.md`.
---
name: scoped-record-boundaries
description: Aligns canonical record commands, read projections, and cache publication under current permission scope. Applies when stale callbacks, relationship aliases, stored metadata, or scenario changes can disagree about which records and actions are available.
---
# Scoped record boundaries
## Contract
- **What:** Carry one canonical record identity through current authorization, visible projections and accepted effects.
- **When:** A control, GraphQL read, cache, count or related-record link bypasses or captures an outdated scope decision.
- **Boundaries:** Browser persona selection demonstrates public example policy; it is not verified human identity. Hosted workspace ownership has its own server boundary. This skill does not introduce accounts, grants or clinical rules beyond the task.
- **Result:** Every receiving view and command agrees on the current permitted record, including explicit denial and missing data.
## Fit and attention
- **Useful when:** An enabled action outlives its permission decision, a stored record replaces a bundled anchor, or hidden records remain visible through counts, aliases or cache publication.
- **Poor fit when:** A purely decorative change never changes data or authority. Authentication design and clinical eligibility policy require their separately authorized decisions.
- **Smallest useful dose:** Follow one command or relation from canonical identity through fresh policy, accepted effect and its visible consumers.
- **May under-attend:** Projection agreement establishes application policy behavior. Verified human identity, legal compliance and external clinical suitability need their own evidence.
- **Interactions:** [Async draft recovery](#document-agents-skills-async-draft-recovery-skill-md-af57d63e7cb0) preserves edits through delayed acceptance; [responsive intent handoff](#document-agents-skills-responsive-intent-handoff-skill-md-3336bb741665) carries permitted selection across renderers. Neither replaces authorization here.
## Inputs, defaults and output
Read the canonical record owner, policy functions, current actor/scenario reader, command and related read/cache consumers. Identify:
| Input | Decision it controls |
| --- | --- |
| Canonical record and ownership metadata | Which consent, geography, classification and relationships govern this record? |
| Acting scope | Who submits the action, in which environment and role? |
| Requested operation | Which capability and legal transition apply? |
| Record identity versus shared object identity | What must be authorized, and what effect can be deduplicated? |
| Read outcome and captured scope | Which authoritative values may replace examples, and where may the response publish? |
Use current policy and source metadata. If canonical ownership is unavailable, preserve the explicit denial/unavailable receiver until it can be resolved; a guessed relationship supplies no authority. The output is a source-grounded command/projection repair and an observation that distinguishes allowed, refused, missing or obsolete input. A new global permission framework is unnecessary when the shared owner already fits.
## Rules
### Rule: The command resolves facts; the view expresses intent
Pass record identity and the requested operation to an accepted-state owner. Resolve current metadata, ownership, consent and legal transition there, then check current authority immediately before the effect. A previously enabled button or successful preview is not a later grant. A displayed or inspected person is distinct from the actor submitting a change.
### Rule: Identity has more than one useful key
A result's record identity can carry consent while several results reference one physical file. Deduplicate a file restore by its physical object key while authorizing each initiating result against its own canonical owner. Choose the identity matching the operation instead of spreading one convenient ID across every layer.
### Rule: Project the whole visible relation
Filter records, fields, counts, stories and relation targets from the same current scope. A hidden target can otherwise remain discoverable through an alias or summary. Stored metadata replaces its bundled anchor, including an explicitly missing well or empty history. Denial and authoritative unavailability suppress fallback; successful retry reopens the receiving path. Distinguish an authoritative unavailable record from a transport exception: the latter reports a failed read without inventing an empty record or a new permission grant. The existing receiver owns whether previously permitted cached data remains visible.
### Rule: Partition and publish independently
A cache key identifies the scope that produced a read. Publication also checks that the current scope still matches when the response arrives. Abort reduces obsolete work, but a current-scope check protects the gap before effect cleanup. Scope-neutral repository reads and request-owned projections keep policy from contaminating shared raw data.
## Operating sequence
1. **Locate authority:** Name the record and actor that the command resolves at acceptance. Distinguish an inspected person from the person submitting a grant change.
2. **Follow identity:** Trace record IDs, relation IDs and physical-object keys through the operation. Choose a key for each job instead of treating display identity as universal.
3. **Inspect acceptance:** Find the current-scope read immediately before the effect. Check the legal transition and already-accepted outcome alongside authorization; an earlier preview remains advisory.
4. **Inspect projection:** Follow the same record into lists, counts, stories, indexes and relation targets. Verify that a denied or missing target leaves those routes through the shared projection.
5. **Inspect publication:** Partition reads by producing scope and compare captured/current scope again at response acceptance. Abort conserves work; publication checks protect the interval before effect cleanup.
6. **Observe the boundary:** Choose the plausible fault: scope changes after preview, a late read crosses scope, or stored ownership contradicts an example. Assert the accepted effect and visible relation independently, using the existing layer that owns each.
7. **Return:** Explain the permitted behavior, current refusal and retry/return route. Separate source inspection, executed policy assertions, browser projection and hosted identity claims.
## Local receivers
- [Shared permission scope](#source-654aee7d8fc3) and [current write gate](#source-f38b3c364c64): policy and fresh scenario access.
- [Plate commands](#source-ae2e63694603): canonical resolution, capability distinctions and physical-file effects.
- [Scoped server repository](#source-dcd81dd09d07) and [history cache](#source-b8b7b608e5d1): request projection and late-publication boundaries.
- [Scoped client observations](#source-ce14ddf2e770) and [permission contract](#document-docs-permission-scenarios-md-cbea28e234a3): covered failures and standing scope semantics.
The scoped-client cases cover actor/inspected-target separation, late publication before effect cleanup, revoked indexes/aliases and stored-anchor replacement. [Plate command cases](#source-6600c62ea770) own current-record acceptance and shared physical-file effects. [Server read cases](#source-ebd13510bf7c) and [scope browser journeys](#source-8e3708d69159) supply their respective projection observations. These are executable coverage owners, not an assertion that they ran during this invocation. Use the [local writing guide](#document-agents-skills-declarative-skill-authoring-references-writing-and-evidence-md-b2b19351a072) when refusal messages or substantial handback prose change.
## Authored routing example
- **Given:** A restore preview is allowed for a result, and several results reference the same file.
- **When:** Canonical consent or acting scope changes before acceptance.
- **Then:** The command resolves the current initiating result and returns its current refusal before starting a restore. Another permitted result may independently authorize the shared-file operation; its readable alias remains subject to that result's policy.
This authored scenario clarifies authorization versus deduplication. The linked command and projection tests establish their asserted cases; the example leaves untested alias combinations unspecified.
## Recovery and re-entry
When policy changes, derive the new projection and discard obsolete publications while retaining unrelated accepted work. Offer a current permitted record or the existing retry when an authoritative read becomes available. For stale edit intent, preserve the draft through its editor owner and recheck authority on the next submission. A missing identity mechanism remains a separately scoped decision; browser persona controls continue to describe public examples.
## Completion
Complete when current commands and projections agree, obsolete reads stay outside the receiving scope, and the affected refusal has a truthful return path. Re-enter when canonical ownership, an action capability, a relation consumer or an identity boundary changes. Keep purely visual work with its existing rendering owner.
## `.agents/skills/test-suite-composition/SKILL.md`
Source document: `.agents/skills/test-suite-composition/SKILL.md`.
---
name: test-suite-composition
description: Designs meaningful checks and composes existing suites around a named behavior, its source owners, prerequisites and recovery. Applies when a change needs a new test, a passing test misses a plausible fault, check selection is unclear, or repeated preparation obscures useful feedback.
---
# Test suite composition
## Contract
- **What:** Connect one intended behavior to a discriminating observation, then select the smallest execution route that can establish it.
- **When:** A collaborator adds or repairs tests, changes an adapter or shared dependency, reorganizes suites, or needs to reduce repeated setup while retaining useful evidence.
- **Boundaries:** The accepted behavior and its source owner define the expectation. Current user instructions and repository policy define authority. A selected or passing check establishes only its exercised claim; merge, hosted deployment, identity and clinical use retain their separate owners.
- **Result:** An existing check or focused addition, a discoverable command population, and a concise result that identifies executed behavior, remaining uncertainty and recovery.
## Fit and attention
- **Useful when:** A test can pass through the wrong path; async responses cross accepted-state boundaries; browser behavior depends on layout or event ownership; several commands overlap; or setup dominates feedback time.
- **Poor fit when:** One direct source reading or existing focused check already answers the question. A simple prose edit usually needs source/link review and a diff check. Unsettled product meaning first needs a decision from its owner.
- **Smallest useful dose:** One behavior, one consequential plausible fault, one independent expectation and the existing runner that observes the difference.
- **Foregrounds:** Useful assertions, source ownership, admitted test population, prerequisites, cost, side effects and retained state after failure.
- **May under-attend:** A good source map cannot establish measured performance, physical-device behavior or successful hosting. Those require their actual receivers.
- **Interactions:** [Async draft recovery](#document-agents-skills-async-draft-recovery-skill-md-af57d63e7cb0), [scoped records](#document-agents-skills-scoped-record-boundaries-skill-md-21058871cd20), [responsive handoff](#document-agents-skills-responsive-intent-handoff-skill-md-3336bb741665) and [resource lifetimes](#document-agents-skills-resource-admission-lifetimes-skill-md-cc56fa51b2d5) supply domain invariants when their triggers fit. [Skill authoring](#document-agents-skills-declarative-skill-authoring-skill-md-c0052dbaf783) owns reusable instruction changes. The [selective-check runbook](#document-docs-runbooks-selective-check-delivery-md-0b5f34c348ca) orders an already-understood check and delivery route.
- **Rest or release when:** The named receiver can select, execute, interpret and recover from the route, or a smaller existing observation completes the task.
## Inputs, defaults and output
Read the current request, [README](#document-readme-md-b33563055168), affected implementation, nearest contract, [package scripts](#source-7ae45ad102ea), existing tests and relevant runner configuration. Establish the branch, revision and working changes. Preserve unrelated work. Identify whether the result concerns a pure rule, command owner, adapter, browser interaction, database engine or delivered package.
The minimum working input is a sentence connecting the action to its consequence, for example: “An ambiguous Source save retries its original intent, so a lost response does not create a second accepted command.” Add the source owner, smallest representative input, plausible faulty alternative, expected signal and execution prerequisites. If one is unknown, inspect the owner or ask for the missing product decision while continuing independent work. Keep an unavailable environment explicit.
Use Node's existing test runner and Playwright by default. Reuse established fixtures and cleanup mechanics; keep expected domain values visible in the case. Prefer one literal, consequence-bearing fixture over a large generated population. Add a dependency, shared harness or suite registry only when an observed repeated problem warrants that owner.
The output can be a direct observation, an authorized test change, or a selected route through existing checks. Its receiving record names the exact source, command/population, preparation, normalized result, exercised claim, skips or remaining gaps, and next action when one exists. Use the existing PR or Issue instead of creating a parallel evidence ledger.
## Rules
### Rule: The intended behavior gives the test its meaning
State what the correct owner retains, accepts, refuses or reveals. Name a plausible faulty implementation and the observation that distinguishes it. A test title should describe that difference rather than a private function call. A click that returns successfully establishes less than an accepted record that survives navigation and reaches its next consumer.
### Rule: The expectation has an independent basis
Derive expected values from a literal fixture, accepted requirement, separately reasoned invariant or independent calculation. Calling production logic to calculate both actual and expected values verifies only the remaining parity relationship. Add an independent semantic anchor when correctness is the question. Require meaningful record membership before comparing two projections; two empty collections can agree while the visitor's task remains unserved.
### Rule: Observation depth follows the plausible fault
Use a pure check for normalization or transitions, a command-owner check for permission/revision/accepted-state rules, an adapter or HTTP check for transport ownership, and an actual browser for responsive remounts, focus, gestures and rendered state. Database atomicity and SQL execution need the disposable engine route. A source-text assertion fits a declared static contract; it cannot replace behavioral evidence merely because implementation text is easy to match.
### Rule: Fixtures separate states that matter
Choose distinct records, revisions, actors and accepted values when the fault could confuse them. Differentiate absent from zero, denied from unavailable, local from stored, pending from accepted, and a stale completion from a current request. For an async race, control completion order with a deferred operation or owned clock. Fixed sleeps and large random matrices can obscure the cause; use them only when their timing or distribution is itself the question.
### Rule: Shared mechanics preserve independent assertions
Helpers can own serving, temporary files, clock control, browser setup and teardown. Cases own the expected values and consequences. Register cleanup before acquiring the next resource; preserve cleanup after partial initialization, rejection and interruption. Keep shared accepted-state fixtures fresh per case. A helper extraction earns its place when it removes repeated mechanics without hiding which record, refusal or recovery failed.
### Rule: Selection and execution remain distinct
A command plan names intended coverage. Discovery reveals admitted cases and may execute test-module initialization. A runner result establishes which cases passed, failed, skipped or were cancelled. A zero-match selector leaves the claim unobserved. Inspect names and scenarios when migrating commands: equal test counts alone leave membership, fixtures and assertions unresolved.
### Rule: The smallest adequate route runs first
Run the affected owner while editing. Expand when a changed adapter, shared state owner, fixture, dependency or explicit release receiver reaches more families. A runtime-neutral document edit receives document proof. A shared dependency or release candidate receives the complete ordinary route; real SQL and hosted acceptance remain separate choices when required by that change. Optional workflow controls conserve work; they do not turn an omitted required observation into a pass.
### Rule: Preparation reuse binds identity
Reuse an existing installation or build only while its relevant source, lockfile, runtime, configuration and environment remain compatible. Rebuild after source changes that affect `dist` or `build/server`. Package caches supply dependency bytes for verification; they do not supply accepted test results. GitHub's preparation composite shares instructions and package-cache use across jobs, while the Browser job can reuse one install/build across its selected steps. A current runner-Chrome smoke result and locked Playwright Chromium result retain their distinct browser identities.
### Rule: Expensive families have explicit entry and cleanup
Use the [automation contract](#document-docs-development-automation-md-c3633dd085ca) for current defaults. Optional workflows' `run_checks=false` skips the whole job before allocation; Verify change always executes its selected required route. Browser and compatibility-database runs are manual choices; PostgreSQL proof has its explicit local native/Compose routes. A database proof requires an independently provisioned disposable loopback database; the guarded runner owns destructive ordering and reseeding. A loopback address alone cannot establish that a tunnel leads to disposable data. Keep secrets and raw traces with their protected runtime owners.
### Rule: Optimize the measured phase
Separate package preparation, browser/system setup, build, behavior execution and artifact delivery before changing a slow route. Preserve the chosen behavior population and failure standing while adjusting preparation. Use existing runner capability and supported package caching first. Additional images, cache registries or parallel jobs need a demonstrated benefit and a maintenance owner. Record observed timings with source, population and environment; a proposed optimization supplies no measured saving.
### Rule: Results retain their exact standing
Report executed pass, failure, skip with reason, incomplete prerequisite, cancellation and prior evidence reuse distinctly. A required case skipped for absent configuration leaves its selected claim incomplete. Reusing an unchanged earlier observation retains its original source and scope; it is not a new execution. A failed test can expose product, fixture or environment faults. Change an expectation only when its accepted contract supports that correction.
## Operating sequence
1. **Locate:** Read current source, tests, contracts and accepted work. Identify the behavior owner and consequential downstream consumers.
2. **Frame:** Name the intended state, plausible fault, independent expected result and smallest observation layer.
3. **Select:** Find an existing case or add a focused one. Choose exact files/cases and the condition that would expand the route. Use the conditional references below for commands and concrete fixtures.
4. **Prepare:** Verify the declared toolchain, dependencies, current build and required disposable services. Discover browser cases before costly execution when membership is uncertain. Keep cleanup active after partial setup.
5. **Observe:** Run the selected population. When useful and safely isolated, show that a controlled faulty variation changes its signal; restore that variation before delivery. A focused regression can also demonstrate the prior fault directly.
6. **Interpret:** Confirm the intended path actually executed. Inspect failures before rerunning; distinguish test admission, fixture, implementation and external prerequisite outcomes.
7. **Expand when warranted:** Follow changed dependency edges or the release contract. Preserve prior valid evidence, and rerun only what the changed source or remaining uncertainty reopens.
8. **Receive:** Request independent review at the intended commit, report the bounded result in the existing PR, and leave hosting or additional authority with its named receiver.
## Conditional context
- Load [source owners and commands](#document-agents-skills-test-suite-composition-references-source-and-command-map-md-f30f1f46ce54) when selecting a suite, preparing a clone or adding a test that needs to join normal discovery.
- Load [test design and recovery](#document-agents-skills-test-suite-composition-references-test-design-and-recovery-md-c721a76a4631) when an oracle, async race, fixture lifecycle, performance assertion or failure meaning needs definition.
- Use the local [writing guide](#document-agents-skills-declarative-skill-authoring-references-writing-and-evidence-md-b2b19351a072) for material test guidance and result prose. Desired behavior leads; exact safety, executable and evidence boundaries retain their meaning.
## Recovery and completion
Preserve accepted edits and unrelated work while resolving the smallest failed owner. A missing browser, occupied server port, unavailable registry or missing build receives its own preparation repair. A consequential assertion failure stays visible while the implementation or supported expectation is repaired. Keep a direct dependency-install route when cache restoration fails. A destructive database route that cannot establish disposable ownership stops before execution.
Complete when the receiver can identify the behavior established, the fault distinguished, actual population and standing, environment identity and coverage boundary. A new command must be discoverable through an existing local owner and keep prior required coverage or explain its intentional replacement. Reopen after a missed defect, source-contract change, new material environment or misleading result. A newly authored skill or runbook remains a working method until a fresh receiving exercise supplies separate evidence of usability.
## Provenance
Adapted from the public exemplars' [suite composition](https://github.com/driftframestudios/human-ai-systems-exemplars/blob/main/.agents/skills/test-suite-composition/SKILL.md) and [evidence-bearing test design](https://github.com/driftframestudios/human-ai-systems-exemplars/blob/main/.agents/skills/evidence-bearing-test-design/SKILL.md). This local skill and references contain the complete operative method for an independent clone; upstream guidance informs review rather than silently changing repository obligations.
## `.agents/skills/test-suite-composition/references/source-and-command-map.md`
Source document: `.agents/skills/test-suite-composition/references/source-and-command-map.md`.
# Source owners and command selection
Load this map to choose an existing test family, prepare a clone, or place a new test. Current [package scripts](#source-7ae45ad102ea), [Playwright configuration](#source-797321ff66b9) and [workflows](#source-87ee5504a3e2) own executable selection. This map explains their receiving jobs; inspect source when a command or owner changes.
## Prepare only what the selected route needs
Read the supported Node line and exact pnpm version from `package.json` and `.mise.toml`, then run `pnpm install --frozen-lockfile`. A package-store hit still receives frozen dependency verification. Node tests use `node:test` and `node:assert/strict`; several TypeScript owner tests transpile their selected modules through the installed TypeScript package. Transpilation exercises behavior and leaves type checking to `npm run typecheck`.
Run `npm run build` before tests that inspect `dist`, import `build/server/example-data.mjs`, use the production server fixture or exercise a browser. The build writes browser and private-server projections. Rebuild when source/configuration affecting either projection changes. Pure source-transpiling tests can run without this build; read the selected file's imports rather than assuming every Node test has the same prerequisite.
Install the locked local browser when needed with `pnpm exec playwright install chromium`; Linux environments may need `pnpm exec playwright install --with-deps chromium`. A compatible existing Chrome/Chromium executable can be selected through `BROWSER_EXECUTABLE`. Record that browser identity rather than describing it as the pinned engine. The Actions smoke route makes this distinction explicit.
## Exact command routes
Commands below run from the repository root. Replace a selected filename or case name only after locating the actual owner. A discovery command establishes selection, not passing application behavior.
| Receiving question | Command | Prerequisite and scope |
| --- | --- | --- |
| Does Source metadata retain its canonical identity and provenance? | `node --test tests/source-session.test.mjs` | Dependencies installed; focused command-owner behavior. |
| Does async Source state preserve retry intent and revision ownership? | `node --test tests/source-workspace.test.mjs` | Dependencies installed; browser service owner with controlled transport. Actual cookie/SQL behavior remains separate. |
| Does one named case execute? | `node --test --test-name-pattern='ambiguous retry' tests/source-workspace.test.mjs` | Inspect executed versus skipped cases; a changed title can leave this selector with no meaningful execution. |
| Which browser cases will run? | `pnpm exec playwright test --list tests/browser/responsive-exploration.spec.mjs` | Installed Playwright; module discovery may execute imports. No browser result is implied. |
| Does selected scene intent survive responsive receivers? | `npm run test:browser -- tests/browser/responsive-exploration.spec.mjs` | Fresh build, compatible browser and free port 3200. |
| Do API/session boundaries agree with built private data? | `node --test tests/graphql.test.mjs tests/workspace-api.test.mjs tests/workspace-session.test.mjs` | Fresh build; tests own synthetic inputs and their transport fixtures. |
| Are the current types and known 3D style carriers valid? | `npm run typecheck` and `npm run check:3d` | Types/configuration and the declared literal-style guard respectively; neither observes the rendered 3D scene. |
| Does the mobile startup graph stay deferred and within budget? | `npm run test:startup` | Fresh production build; emitted manifest/asset graph, not measured network latency. |
| Does the ordinary Node test population pass? | `npm test` | Fresh build and installed dependencies; shell selection is `tests/*.test.mjs`. Optional real-engine cases may skip. |
| Does the ordinary production browser population pass? | `npm run test:browser` | Fresh build and installed browser; `tests/browser/*.spec.mjs` admitted through Playwright. Stored-workspace cases have a separate database opt-in. |
| Do real catalog/workspace operations work on MySQL? | `npm run test:mysql` | Fresh build, MySQL CLI and independently provisioned disposable database; see service contract below. |
The [README verification route](#document-readme-md-b33563055168) composes types, 3D guard, build, aggregate Node tests and ordinary browser tests for shared changes or release candidates. A particular API or browser claim can still need a focused case that the aggregate lacks.
## Owner-to-test starting points
These are routing examples rather than an exhaustive dependency registry. Follow changed imports and consumers with `rg` before deciding that a focused file covers the full change.
| Behavior owner | Existing evidence and useful extension point |
| --- | --- |
| [Source command preparation](#source-d176065b3445), [async workspace owner](#source-78bb60083fcc) | [source-session](#source-70e4a3035b20), [source-workspace](#source-e0f8fa0df343), [Source operations browser](#source-c46e0eda1019). Hosted acceptance adds [workspace API](#source-6869c1621f3e), [PostgreSQL store](#source-b6a908149d8b) and [stored browser](#source-11cee35cf6d2). |
| [Permission kernel](#source-654aee7d8fc3) and [current scenario](#source-cdae7aff6d99) | [permission policy](#source-48024a9a161b), [scoped reads](#source-ebd13510bf7c), [scoped client](#source-ce14ddf2e770) and [scenario browser](#source-1284bdf045a7). A disabled button alone leaves direct command refusal unobserved. |
| [Shared exploration](#source-5fb8b7d40fe1), [guide model](#source-b3d02099d119) and actual scene receivers | [guide state](#source-9c1afdaf9e5e), [responsive exploration](#source-d9c338cfe457), [guided browser](#source-9df344b56900). Test actual receiving selection and cancellation, not a second remount-time default. |
| [Plate command owner](#source-ae2e63694603), histories and scene motion | [Plate commands](#source-6600c62ea770), [history client](#source-f388508046fc), [scene transition](#source-ed6e89432ca6) and [Plate browser commands](#source-71ebc9d23f47). |
| Accepted specimen, release, Map, QC, artifact and cohort services under [services](#source-85ffad43f38c) | Matching `record-commands`, `release-workflows`, `map-operations`, `qc-reviews`, `artifact-workflows` and `cohort-session` Node tests; corresponding named browser files under [tests/browser](#source-39d9310e8039). Preserve distinct canonical records and refusal/recovery in fixtures. |
| [Request admission](#source-594a5cb2c755), [read API](#source-2b0fb69c1d4e) and [workspace API](#source-81a2088fda22) | [request-admission](#source-195769eedd8c), [graphql](#source-b986f196fa2a), [workspace-api](#source-6869c1621f3e), [document-policy](#source-72ed30ed248f). Controlled deferred handlers distinguish returned deadlines from underlying cleanup. |
| Build and ordinary startup under [scripts](#source-8c5967fd8486) | [startup-bundle](#source-e8970b155997), [deployment](#source-36faf1c67eb0). [server-fixture](#source-52688c2d3aae) owns temporary server preparation and teardown. |
Place new ordinary Node cases in `tests/*.test.mjs` and browser cases in `tests/browser/*.spec.mjs` when those existing discovery rules fit. A new file outside those patterns needs an explicit runner owner. Real-engine `mysql-*.mjs` tests deliberately belong to the guarded database composition. Add new engine phases through that owner and verify order, cleanup and reseeding. A generic “run every test file” glob can destroy the fixture another family needs.
For PostgreSQL engine or clone changes, use the [native populations](#document-docs-postgresql-md-a7cc27814ec8) or [Compose proof](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277). Those routes own explicit engine/project preparation; ordinary tests retain their independent scope.
## Service and browser lifecycle
The browser configuration runs one worker with zero retries, rejects focused-only tests, and serves the production build on port 3200 with `reuseExistingServer:false`. A busy port is a coordination failure to resolve, not a reason to attach to an unknown build. A separate ignored configuration can supply another port for parallel investigations while retaining the repository-root working directory and matching base URL. Extra browser contexts receive explicit closure; local screenshots/traces remain in ignored `.visual-runs`.
Ordinary browser storage marks the optional guide as already seen. The guide-specific suite intentionally supplies first-arrival storage. A new journey should choose that state explicitly when the opening invitation matters, rather than changing unrelated tests' baseline.
The [database runner](#source-a65b7b4c6772) requires `DB_HOST`, `DB_NAME`, `DB_USER` and `DB_PASSWORD`; `DB_PORT` defaults to 3306. It accepts only loopback and a database named `sot_*_test` or `sot_*_proof`, sets its own opt-ins and requires a MySQL CLI (`MYSQL_CLIENT` can select one). For an explicitly prepared ignored local file, `node --env-file=.env scripts/prove-database.mjs` loads those settings. Verify independently that the endpoint is disposable; a forwarded hosted connection can still appear as loopback.
The runner orders destructive workspace proof before catalog proof, then initializes both families before workspace HTTP checks. It stops at the first failed phase and leaves initialized tables after success for a separately requested stored-browser journey. The ordinary aggregate and ordinary browser suite do not substitute for that engine result. Hosted data remains outside all test setup.
For a Source editor, reload or uncertain-response UI claim, retain that same disposable server and its exported `DB_*` environment after the proof, then run:
```sh
WORKSPACE_BROWSER_DATABASE=1 npm run test:browser -- tests/browser/source-workspace.spec.mjs
```
The flag admits the three stored-workspace browser journeys; the fresh production build, initialized database and free port 3200 remain prerequisites. Database proof itself runs engine/HTTP cases, not this browser file. Without the explicit opt-in, these journeys skip and leave the stored UI claim unobserved. Release the independently owned database after the final selected check.
## Manual workflow choices
The [automation contract](#document-docs-development-automation-md-c3633dd085ca) and YAML own the current policy:
- Verify change receives every main PR with a docs/Core selection and committed-tree scan. The inactive main profile requires that unfiltered job; Core also remains an optional manual route.
- Optional dispatches default `run_checks=true`; false skips before runner/services. Verify change always runs. A skipped optional route supplies no behavior evidence.
- Browser defaults to `scene-smoke`: the core, responsive-exploration and guided-exploration files. It uses runner Chrome with a version receipt, falling back to locked Chromium. `all` uses locked Playwright Chromium.
- `include_core=true` runs types, the CSS 3D guard and aggregate Node checks in the same Browser job. For complete ordinary interaction proof select `all` with this option.
- Optional MySQL compatibility proof and publication scan are separate manual choices. PostgreSQL uses the explicit native/Compose routes, with a [manual clone workflow](#source-8ab7cc430f4a) for the same container proof. Selected runs share resources only within their job. The shared preparation action caches package bytes and does not reuse another job's VM, build or test result.
When a workflow changes, inspect the proposed revision and dispatch the affected route deliberately. Built-artifact inspection, GitHub publication and actual application deployment remain separate observations and authority boundaries.
## `.agents/skills/test-suite-composition/references/test-design-and-recovery.md`
Source document: `.agents/skills/test-suite-composition/references/test-design-and-recovery.md`.
# Independent expectations and recoverable checks
Load this reference when a test could pass for the wrong reason, async order matters, or a failure loses useful diagnosis. It supplies concrete decisions; executable cases remain with their current source owners.
## Frame a useful case
Write these six answers before expanding a fixture:
1. **Behavior:** What does the visitor or next consumer rely on?
2. **Owner:** Which command, state store, adapter or renderer creates that state?
3. **Fault:** What plausible implementation would produce a materially different result?
4. **Independent expectation:** Which literal record, accepted invariant or separately reasoned value supplies the answer?
5. **Observation:** What assertion distinguishes the fault at the smallest adequate layer?
6. **Recovery:** Which accepted record, draft or resource must remain after refusal or interruption?
If the result remains the same under the proposed fault, revise the fixture or observation. A test need not explore every arithmetic permutation: a representative case that distinguishes the wrong owner, direction or denominator can be stronger than many implementation-shaped assertions.
## Examples grounded in this repository
These examples describe test design. The linked executable cases carry their own observed results.
### An ambiguous save retains its intent
The [Source workspace tests](#source-e0f8fa0df343) inject a controlled transport and ID factory. Distinguish a lost response after acceptance from a definite refusal. Capture the dispatched ID, expected revision and metadata, then retry the unchanged submission. Assert the repeated command identity and retained draft/accepted projection. A helper that generates a new expected ID on both sides would hide the fault.
Keep the engine's [receipt proof](#source-655391fe8176) separate: it verifies that an exact retry returns its recorded result without accepting another changed event. A later accepted revision may exceed the replayed receipt; the client must retain the newer projection. The pure service case establishes ordering logic, while the stored browser and real-engine routes establish their receiving transport and persistence.
### Responsive receivers retain the chosen record
The [responsive exploration journey](#source-d9c338cfe457) selects a named well/result and history options, changes viewport, and reads them in the receiving layout before returning. Use distinct choices that differ from defaults. Assert the receiving selected identity, mode and options, rather than clicking them again after resize; repeating the selection would repair the fault inside the test. A component-only test cannot establish the actual breakpoint/remount path.
### Direct commands preserve scope and accepted state
For a permission change, invoke the actual owner using an admitted record, then a distinct denied or stale input. Assert a typed refusal, unchanged accepted data and any draft recovery that belongs at that layer. Readable parent data does not imply every nested record is readable. Separate actor authorization from the inspected person and cover a second record when cross-record leakage is plausible. A disabled button is useful UI evidence and leaves direct command enforcement to its owner tests.
### A deadline ends the response before work ends
The [request-admission tests](#source-195769eedd8c) hold a handler with a deferred promise, fill capacity, observe the refusal and release the underlying work. An assertion made only after the handler settles cannot distinguish a slot released too early. Register a cleanup release before awaiting the operation so an earlier assertion failure still permits teardown. Inspect the refusal's stable status/code and the next admitted request, while keeping arbitrary diagnostic text out of the oracle.
### An animation test observes motion rather than machine speed
The [Corridor camera journey](#source-303246a2d817) uses a controlled browser clock and reads intermediate/final transforms. Preserve its initial transform, motion phase, settlement and manual cancellation assertions. A controlled clock can establish the transition contract across slow runners. It does not establish frames per second or perceived smoothness; those receive real-time inspection with the actual device/runner. Increase a timeout only after identifying the delayed owner, rather than replacing a failing motion assertion with a final-state-only check.
## A fixture lifecycle that survives failure
Keep fixture data minimal and recognizable. Choose separate identities where confusion matters, bind a clock when time changes the expected value, and reset mutable state per case. A synthetic fixture avoids touching a real laboratory or hosted account. Prefer dependency injection already present in the command owner over global monkey-patching.
Register `t.after` cleanup before creating the next server, directory, pending operation or connection. A resource reference may remain absent after partial setup; its cleanup should still be safe. Await process exit and release owned handles before removing fixture storage. The [server fixture](#source-52688c2d3aae) demonstrates early cleanup registration and private fixture-server ownership. Browser tests should close additional contexts and release intercepted/deferred requests in a `finally` block or owned teardown.
Reuse fixture mechanics only when lifecycle and error behavior agree. Cases retain their own source-specific assertions. A large helper that silently normalizes expected records can erase the distinction a regression needs. Conversely, duplicated fixture startup that leaks on failure is a useful candidate for consolidation.
## Interpret the result before rerunning
| Observation | What it establishes | Next action |
| --- | --- | --- |
| Named assertions passed on the selected revision | The exercised path and fixture satisfy those expectations. | Expand only for changed dependencies, unresolved uncertainty or a required receiver. |
| Discovery lists the intended cases | Selection and module loading succeeded. | Run them with required preparation before claiming behavior. |
| Selector matches zero cases or every relevant case skips | The intended claim remains unobserved. | Repair the selector or admit the prerequisite; keep the incomplete result visible. |
| Dependency/browser/build prerequisite is absent | The check could not reach its intended observation. | Prepare that owner and rerun the same selected route. |
| Assertion differs from the accepted behavior | A product or test-contract discrepancy exists. | Inspect actual state and the independent oracle; repair the supported owner. |
| Timing varies while functional assertions pass | Timing remains an environment-specific observation. | Compare phases and population before changing worker count, caching or budgets. |
| A late error arrives after an apparent success | Completion was observed before all owned work settled. | Await final telemetry/cleanup and publish the complete standing. |
| A job is cancelled | Only already-completed observations retain their scope. | Confirm teardown or dispose of the isolated environment, then resume the missing route. |
Retain the original meaningful failure while repairing its cause. Changing fixtures is appropriate when source authority proves the prior fixture stale. Label that as an oracle repair and explain the behavior preserved. A retry that happens to pass leaves intermittent behavior for investigation; retries are not a substitute for defining readiness or resource ownership.
## Add or move a test without widening the harness unnecessarily
Extend the existing owner file when it keeps the behavior discoverable. Add a named file when it gives a distinct source owner or lifecycle a clearer home. Use parameterization for rows that express real boundaries; retain descriptive case names and independent expected values. When moving a case or sharing setup, compare case identities, fixtures, skip conditions and failure standing before and after. Counts alone cannot prove equivalent coverage.
A new runner or dependency needs a capability the current Node/Playwright pair cannot reasonably supply, plus an owner for configuration, installation, cleanup and delivery cost. A new command should state its prerequisites and membership in the nearest README or conditional command map. A global registry is optional; direct commands are a complete composition when they remain easy to select.
The final result belongs in the existing PR or Issue: selected source/commands, normalized pass/fail/skip standing, the behavior established, limits and the next owner when needed. Keep credentials, raw logs, browser state and protected host details with their authorized local or service owner. This result can support independent review; it does not grant merge or hosting authority.
## `AGENTS.md`
Source document: `AGENTS.md`.
# Source-of-Truth Life Sciences
React, Vite, and Tailwind visual prototype with an isolated PostgreSQL clone and an ordinary Node server. Read `README.md` for the deployment and local development routes. Preserve the existing interface while addressing the current task.
- `npm run dev:source` runs the local Vite server with hot reload.
- `npm run build` produces `dist`; `npm start` serves that production output.
- `npm run dev` and `npm run dev:source` run Vite for interface development; Node build/start owns the GraphQL APIs.
- `scripts/serve.mjs` owns production HTTP serving and the platform `PORT`.
- `vite.figma.config.ts` retains asset resolution and page metadata transformations.
- `.figma/make/site.json` owns the application title and description.
- `.mise.toml` and `package.json` pin the Node/pnpm toolchain.
Follow the project guidance in `guidelines/Guidelines.md` when it applies. Keep publication artifacts tied to reviewed source; local caches, environment files and dependencies stay with their private owners.
## Continue a collaboration
Confirm branch, working changes, current issue and nearest source owner before editing. Preserve unrelated work. [Runbooks](#document-docs-runbooks-readme-md-39a19900e08a) carry the focused change, dependency maintenance, database recovery and Node deployment routes. [Automation](#document-docs-development-automation-md-c3633dd085ca) names what each Action establishes and the operator steps that remain separate. Independent review receives the exact proposed revision and its proportionate evidence before an authorized merge.
Repository skills under `.agents/skills/` provide focused reasoning when their trigger fits:
- [publication-boundary](#document-agents-skills-publication-boundary-skill-md-83499c0cb69a): inspect exact source and artifact scopes with a canary-proven detector, sanitized results and a separate metadata reading.
- [test-suite-composition](#document-agents-skills-test-suite-composition-skill-md-412c39ca5e33): design a discriminating test, select its smallest useful suite, and choose CI depth while preserving source identity and cleanup.
- [declarative-skill-authoring](#document-agents-skills-declarative-skill-authoring-skill-md-c0052dbaf783): create or revise self-contained skills and their runbook companions from an observed recurring method.
- [responsive-intent-handoff](#document-agents-skills-responsive-intent-handoff-skill-md-3336bb741665): retain exploration across layouts and deferred scene receivers, including guide cancellation and manual takeover.
- [scoped-record-boundaries](#document-agents-skills-scoped-record-boundaries-skill-md-21058871cd20): align command acceptance, related reads and cache publication with current canonical identity and permission scope.
- [async-draft-recovery](#document-agents-skills-async-draft-recovery-skill-md-af57d63e7cb0): distinguish submitted drafts, accepted records, editor generations and workspace namespaces during hydration or retry.
- [resource-admission-lifetimes](#document-agents-skills-resource-admission-lifetimes-skill-md-cc56fa51b2d5): keep request capacity attached to underlying work until cleanup, even when an HTTP deadline has already returned.
Use the smallest fitting method. These skills guide decisions; user authorization and the actual source determine scope. Local scenario roles demonstrate policy; verified accounts and private-data authority remain a separate future decision. Source publication keeps credentials, private locators and raw traces with their existing private owners; a PR summarizes the receiving behavior, checks, coverage and recovery.
## Maintain reusable instructions
The [selective check runbook](#document-docs-runbooks-selective-check-delivery-md-0b5f34c348ca) carries a known route from a changed owner to focused evidence, optional deeper checks and a reviewed return. Add an executable case when it distinguishes a consequential plausible fault; preserve independent expected outcomes and bounded fixture cleanup. Source maps and configurations determine current populations, so a copied test count remains an observation of its named revision.
Skills and runbooks use the local [writing and evidence guide](#document-agents-skills-declarative-skill-authoring-references-writing-and-evidence-md-b2b19351a072). Name the responsible actor and action, lead with the intended state, and classify negation before revising it. Exact safety, compatibility, privacy and executable boundaries retain their meaning beside a useful continuation. Distinguish authored scenarios, structural checks, independent exercises and runtime observations.
Keep required guidance and source links inside this clone. Public upstream references provide provenance and deeper research; future collaborators can apply the local methods without another checkout, account or conversation. Revise the existing instruction owner when it already carries the job. A new helper or catalog earns its place through repeated mechanics or a consequential boundary.
## `ATTRIBUTIONS.md`
Source document: `ATTRIBUTIONS.md`.
# Attributions
The repository's [LICENSE](#document-license-c693279643b8) carries the owner's copyright and MIT terms. Preserve it together with the upstream notices that apply to adapted components and redistributed dependencies.
## Components
The Figma Make starting material included [shadcn/ui](https://ui.shadcn.com/) components. The retained [ScrollArea](#source-0d3387be4927) and [class-name utility](#source-1a591d68d27d) preserve that component lineage; ScrollArea composes the installed Radix primitive. The [upstream MIT notice](#source-e00040f989fb) is included locally from [shadcn/ui's license](https://github.com/shadcn-ui/ui/blob/main/LICENSE.md).
Other packages retain their own licenses in their distributed packages. [package.json](#source-7ae45ad102ea) and [pnpm-lock.yaml](#source-32824c984905) identify the actual dependency graph; this attribution file does not relicense those dependencies.
## Images
[source-of-truth-systems-social-preview.png](#source-a9dfe37facea) is the maintainer-supplied screenshot of the application's Plate, used for social previews and repository orientation. The current tracked image and imports contain no Unsplash photograph. This supersedes the starter's generic Unsplash credit; restore a specific photographer/image attribution if such a photo is deliberately added later.
The five [README screenshots](#source-585524640b95) were captured locally from the working application using its bundled synthetic examples. They show the desktop Corridor, Sample history and Cohort Builder, plus the mobile Corridor and Sample history. They retain the project's copyright and contain no added stock photography.
## Fonts
[src/styles/fonts.css](#source-7e922fabf053) requests Playfair Display, DM Sans, JetBrains Mono, Archivo Black and Space Grotesk through Google Fonts. The browser contacts Google's stylesheet and font delivery services; font binaries are not bundled in the current source. An offline or network-restricted environment uses the declared fallback fonts, so its typography may differ.
A deployment that needs self-hosted fonts should obtain the selected families and versions from their authoritative distributions, retain each applicable license/notice and review the resulting asset loading. The [Google Fonts FAQ](https://fonts.google.com/faq) describes its licensing and hosting model. Self-hosting is a separate change; the current delivery remains external.
## Creation tools
The owner-confirmed credit is: “Built with Figma Make (Claude Opus 5.5) and ChatGPT/Codex (GPT-6 Astra), using custom coding harnesses from kindlight.systems.” [ShowcaseCredit.tsx](#source-5ff2f1d297be) owns the visible wording. Git authorship and reviewed contributions identify subsequent work; tool credit does not replace copyright or upstream attribution.
[Return to the repository](#document-readme-md-b33563055168)
## `CLAUDE.md`
Source document: `CLAUDE.md`.
@AGENTS.md
## `CODE_OF_CONDUCT.md`
Source document: `CODE_OF_CONDUCT.md`.
# Community conduct
Make repository discussions useful and welcoming. Treat people with respect, explain technical disagreements through evidence and consequences, and give others room to ask questions or revise a proposal. Critique the work without attacking the person.
Harassment, discriminatory abuse, threats and publishing another person's private information are outside this community's boundaries. Keep shared examples synthetic and discuss disagreements in the relevant issue or PR. The maintainer may clarify expectations, edit or remove harmful material, close a discussion or restrict participation to keep the repository workable.
Vikrant Varun Kudesia is the repository maintainer. For a conduct concern, use an existing private contact route only when the maintainer has provided one. Otherwise, ask for a private conversation through a repository issue without including sensitive details or repeating harmful content. Share the details after a private route is agreed. This policy does not imply a staffed reporting service or response-time promise.
These expectations apply to repository issues, pull requests and project discussions. [Support](#document-support-md-c5fe610b0215) and [Contributing](#document-contributing-md-eca12c0a30e2) describe the ordinary working routes.
[Return to the repository](#document-readme-md-b33563055168)
## `CONTRIBUTING.md`
Source document: `CONTRIBUTING.md`.
# Contributing
Help someone understand a workflow, preserve a useful interaction, or make the code easier to extend. A small, clear change is welcome. Start with [the example](#document-docs-getting-started-md-31bcba2ccafa), then read the nearest source README and the contract for the behavior you intend to change.
## Agree on the outcome
Use this repository's Issues tab for a reproducible bug or an improvement proposal. Describe the person using the feature, their intended action, what happens now and the useful result. For a larger feature or dependency change, discuss the outcome before implementing it so the maintainer can identify the fitting scope. Security-sensitive details belong in the [security reporting route](#document-security-md-f6ed156e4bf5).
Vikrant Varun Kudesia maintains this project for Driftframe Studios, LLC. Public issues and PRs are active receiving records. The maintainer may coordinate implementation in a separate working repository, then returns the public decision, relevant checks and resulting change here. Contributors can understand and review a change entirely through public source and discussion. When accepted work is carried between repositories, its Git authorship and agreed co-author credit travel with it; later releases retain ordinary public history.
## Make a focused change
1. Create a branch from current `main`; keep unrelated changes separate.
2. Follow the owner routes in [application](#source-27d865c285d9), [server](#source-93e4a5263a59), [shared contracts](#source-8e14ddd6c044) and [tests](#source-dacac2ebf979). Preserve the current visual language, mobile Corridor/Plate behavior and draft recovery unless the agreed task changes them.
3. Add or adjust a test when it distinguishes a consequential plausible fault. Use the smallest fitting check, then expand for shared dependencies or release boundaries. Format only changed files with `npm run format -- path/to/file.tsx`.
4. Update the existing documentation owner when behavior changes. Keep examples synthetic and publish only sanitized reproduction steps; credentials, patient records, cookies and raw private traces stay outside issues, source and test fixtures.
5. Open a PR explaining the problem, resulting behavior, checks actually run and any remaining observation. For visual changes, include a reviewed, synthetic-data screenshot or describe the affected viewport and interaction. Keep screenshots free of account details.
Independent technical review receives the proposed revision before merge. This solo-maintainer project can record an independent reviewer or coding-agent review in the PR; it does not require a second account's approving-review badge. The maintainer owns acceptance and repository settings. A passing check supports the behavior it exercised; it does not authorize publication or database setup.
Public fork contributions use GitHub's least restrictive workflow-approval policy: only first-time contributors who are also new to GitHub may need a platform-required approval. The repository adds no blanket external-contributor approval requirement. The maintainer reviews workflow, action, installation and build changes before merge, and before approving a run when GitHub requests it. The [public-visibility handoff](#document-docs-runbooks-public-visibility-handoff-md-778a29856725) records how the owner applies and confirms that policy when opening repository access.
## Tests, tools and rights
The [selective check runbook](#document-docs-runbooks-selective-check-delivery-md-0b5f34c348ca) explains focused checks, optional browser/SQL proof and release evidence. Copied workflows remain subject to each repository's Actions settings; [automation](#document-docs-development-automation-md-c3633dd085ca) describes the current selection controls. Keep optional expensive checks deliberate.
AI-assisted contributions use the same source, review and rights expectations as other contributions. Describe relevant generated or adapted material so a reviewer can inspect its origin. Keep applicable upstream notices and the [project license](#document-license-c693279643b8). Submit code and assets you have authority to contribute under those terms; identify material governed by a different license in [ATTRIBUTIONS](#document-attributions-md-5138861280db).
Please follow the [conduct policy](#document-code-of-conduct-md-ffdbe3a1e7ee). Questions about a setup route can start with [Support](#document-support-md-c5fe610b0215).
[Return to the repository](#document-readme-md-b33563055168)
## `LICENSE`
Source document: `LICENSE`.
Copyright © Vikrant Varun Kudesia | Driftframe Studios, LLC
MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
## `README.md`
Source document: `README.md`.
# Source of Truth Systems
Explore how a life sciences team follows a sample through its workflow, reviews changing results and finds the files behind a finding. **Source of Truth for Life Sciences** is the working application in this repository: a visual, interactive example for studying and extending these information relationships.
Use the working components as a starting point for information-dense tools, with responsive layouts, notifications, error recovery, color themes and interactive 3D views already connected. Explore with bundled examples or PostgreSQL-backed records, then adapt the data and Figma Make configuration for your own project.
- [Try the working application](https://kindlight.ai), or run the bundled examples below.
- [Explore the developer documentation](https://kindlight.foundation) to find the code behind the experience.
- [Read the fixture provenance](#document-docs-fixture-provenance-md-8ff275b9c7d1) for the example findings and policy assumptions.
## Explore the workflows
### Follow work through the Corridor
See how work moves from sample intake to reporting. The Corridor keeps each step beside its supporting records, so you can follow the process and inspect what happens along the way.

### Understand a sample's history
Select a well to compare its results over time. The Plate brings sample history, quality, consent and related files together, helping you investigate questions such as why a sample was rerun.

### Build and explore cohort rules
The working rule builder lets you combine conditions and see which example specimens match. Desktop also gives you room to compare specimens, inspect source records and assemble presentations around the findings.

### Explore the Corridor and Plate on mobile
Mobile puts the Corridor and Plate within reach of direct touch controls. Follow the workflow, select a well and open its 3D Sample history; the selected view and records stay with you as the layout changes.
## Run the complete local example
Clone the repository below to run it locally. If GitHub requests access, ask the maintainer for an invitation. The [live application](https://kindlight.ai) remains available to explore.
Install Git, Node **22.15 or newer within 22.x**, and Docker with Compose. The recipe supplies locked application dependencies and a PostgreSQL database owned by this clone.
```sh
git clone https://github.com/driftframestudios/source-of-truth-systems.git
cd source-of-truth-systems
node scripts/clone.mjs configure --port 3000
node scripts/clone.mjs up
```
Open `http://localhost:3000`. Use **Guide** to choose a question or **Watch walkthrough**, or explore the Corridor and Plate directly. C3's Sample history shows **Stored history**. Source title, description and tag edits persist in an isolated visitor workspace for up to 24 hours; other workflow edits last for the current browser session.
`node scripts/clone.mjs stop` preserves the database. Run `up` to return. [Getting started](#document-docs-getting-started-md-31bcba2ccafa) explains configuration and prerequisites; [local operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) covers backup, restore and an explicitly confirmed reset.
For interface-only exploration or hot reload, install pnpm **10.34.3**, run `pnpm install --frozen-lockfile`, then `npm run dev:source`. Open `http://localhost:8443`; this lighter route uses bundled examples and browser-local edits.
## Choose a route
| I want to… | Start here |
| --- | --- |
| Explore the app or troubleshoot local startup | [Getting started](#document-docs-getting-started-md-31bcba2ccafa) |
| Understand state, scenes and retained edits | [Application source](#source-27d865c285d9) |
| Choose persistence or understand database trade-offs | [Database choices](#document-docs-database-choices-md-a44edbfece29): PostgreSQL, bundled examples and optional specialist stores |
| Inspect GraphQL or the current stored-data contracts | [Server and data](#source-93e4a5263a59) |
| Deploy the example | [Node hosting](#document-docs-deployment-md-7f6254f34e12) |
| Make a focused change | [Contributing](#document-contributing-md-eca12c0a30e2) and [test selection](#source-dacac2ebf979) |
| Browse design decisions and interaction contracts | [Documentation](#document-docs-readme-md-0b5ca119d2be) |
| Guide an AI collaborator through a focused change | [Repository skills](#document-agents-md-a54ff182c7e8) |
| Follow a repeatable development or delivery procedure | [Runbooks](#document-docs-runbooks-readme-md-39a19900e08a) |
## Work with an AI collaborator
The repository skills give an AI collaborator practical guidance for recurring work, such as checking code and release files for exposed API keys, preserving unfinished edits and choosing tests that exercise the behavior being changed. They keep useful development practices close to the code so a new collaboration can start with context.
Companion runbooks turn those practices into repeatable steps for making changes, checking dependencies, recovering data and delivering a release. Use the [skills index](#document-agents-md-a54ff182c7e8) to choose a method and the [runbook index](#document-docs-runbooks-readme-md-39a19900e08a) to follow an established procedure. Both travel with your clone and can evolve with your project.
## Verify a change
A small check is available immediately after installing dependencies:
```sh
npm run test:mobile
```
It checks the Corridor gesture owner; a visible interface change also needs an affected-view browser check. For a shared change or release candidate, the complete ordinary route is:
```sh
npm run typecheck
npm run check:3d
npm run build
npm test
pnpm exec playwright install chromium
npm run test:browser
```
Build before the aggregate tests: API and startup checks inspect the generated outputs. The browser suite owns port 3200. Actual PostgreSQL proof is an explicitly selected [isolated database route](#document-docs-postgresql-md-a7cc27814ec8), separate from ordinary tests. [Tests](#source-dacac2ebf979) explains narrower choices, prerequisites and result boundaries.
Main pull requests receive the fitting **Verify change** route and committed-tree scan. Optional deeper checks retain their own scope. The [branch and tag protection contracts](#source-f32a9eda0632) preserve accepted source; the docs branch uses its pinned data-only verification route.
## Deploy or adapt
The complete application runs on Node. `npm run build` creates browser files and private server data; `npm start` serves both with GraphQL. The public edition supports PostgreSQL and bundled examples. Other Node hosts can use the build/start contract and earn their own receiving-host check. A static host serves browser assets but does not provide the application's API or durable workspace. [Deployment guide](#document-docs-deployment-md-7f6254f34e12)
The PostgreSQL adapter and [Compose/native setup](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) persist Plate history and expiring Source metadata workspaces. Each clone owns its local data and generated credentials. [Database choices](#document-docs-database-choices-md-a44edbfece29) explains the current contract and optional property-graph, RDF or object-store extensions.
The ordinary Node build also serves **Developer docs** at `/docs/`, opened in a separate tab so current work stays mounted. `npm run build:foundation` builds the same admitted articles at site root in `dist-foundation/`. The [tagged documentation release](#document-docs-runbooks-tagged-documentation-release-md-33af7f4666be) builds one reviewed artifact and explicitly activates those same files on Pages. The source-derived GraphQL reference and all documentation profiles share [one content manifest](#source-d49fc7030a43).
The repository retains its Figma Make entry scripts and Vite adapter. They provide source configuration for a fresh Make session; a new import still needs verification in that session. The pinned container recipe has its own fresh-clone and recovery proof; a receiving managed host still needs a deployment observation.
## Dependencies and continuation
React, TypeScript, Vite, Tailwind and Motion shape the browser experience. The Node server uses GraphQL Yoga and the `pg` PostgreSQL driver; those dependencies remain outside the browser bundle. [Shared contracts](#source-8e14ddd6c044) preserve record and permission meaning across both sides. The root package and lockfile own the toolchain.
Extend an existing state or command owner before adding a parallel store. Keep synthetic examples useful, preserve current interactions, and test the behavior your change affects. [Local skills and runbooks](#document-agents-md-a54ff182c7e8) support human and AI-assisted development without access to another workspace. Public issues and pull requests are the contribution route; [CONTRIBUTING](#document-contributing-md-eca12c0a30e2) explains review and how accepted contributions retain credit.
## Credit and support
Created by Vikrant Varun Kudesia · Driftframe Studios, LLC. Built with Figma Make (Claude Opus 5.5) and ChatGPT/Codex (GPT-6 Astra), using custom coding harnesses from kindlight.systems. [Attributions](#document-attributions-md-5138861280db) identifies component, image and font provenance. The [MIT license](#document-license-c693279643b8) retains the owner's exact notice.
Use [Support](#document-support-md-c5fe610b0215) for questions and reproducible bugs, and [Security](#document-security-md-f6ed156e4bf5) for a sensitive finding. The [community conduct policy](#document-code-of-conduct-md-ffdbe3a1e7ee) applies to repository discussions.
## `SECURITY.md`
Source document: `SECURITY.md`.
# Security
This repository demonstrates workflows with synthetic records. Selectable personas model policy; they are not verified human accounts. Optional visitor workspaces store bounded Source metadata under an expiring server-issued cookie. Deployers should use the example for evaluation and development; private patient records and real multi-user clinical operations require a separately designed identity, authorization and operational boundary.
## Report a sensitive finding
When this repository's **Security → Report a vulnerability** control is available, use that private GitHub route. Its availability depends on the maintainer's repository settings and is not established by this file.
If that control is unavailable, open an issue asking the maintainer for a private reporting channel, using only a general subject such as “Private security contact requested.” Wait for an agreed private route before sharing reproduction details. Keep exploit payloads, credentials, cookies, personal records and unpublished vulnerability details out of public issues and pull requests.
In the agreed private report, include the affected revision, component, prerequisites, a synthetic-data reproduction and the observed impact. The maintainer can then assess the input path, scope and repair with you. Avoid probing hosted systems beyond your authorization; a local clone is the normal investigation environment.
## Supported source and deployment boundaries
The current `main` source is the maintenance target. Older snapshots and personal deployments need their own update decision; the project does not promise a long-term support schedule. The root package and lockfile identify the dependency graph to assess.
The [input assessment](#document-docs-research-input-boundaries-md-c7dbe8e1d24d), [GraphQL contract](#document-docs-graphql-read-api-md-03dad145256f), [permission scenarios](#document-docs-permission-scenarios-md-cbea28e234a3) and [workspace contract](#document-docs-visitor-workspaces-md-49294a63218a) describe the implemented boundaries and their limits. Registered GraphQL operations and scenario permissions are useful controls, but neither establishes a person's identity. Keep database settings in the hosting secret store or an ignored local environment file. Ordinary application startup preserves stored data; schema setup is an explicit operator action.
## Current dependency exposure
The 2026-11-17 assessment retains an open high-severity dependency finding: [GHSA-fc5q-39xc-vjpf](https://github.com/advisories/GHSA-fc5q-39xc-vjpf) affects `picomatch` through `4.0.7` and lists no patched version. The [lockfile](#source-32824c984905) includes `picomatch@4.0.7` in the Vite `6.4.6` build graph, including `tinyglobby` and `fdir`. This assessment describes the current exposure; it does not claim a dependency fix.
Glob patterns are developer-controlled source: [asset matching](#source-6a3b01ba9782), [story discovery and watcher exclusions](#source-ef189d75061e), and [Tailwind source scanning](#source-69234e047cf7). Application forms, URLs and GraphQL inputs supply none of these patterns. Contributors can propose configuration changes through review. The ordinary production command starts the [Node server](#source-16966778dca8), which serves built assets and GraphQL without running Vite; the installed dependency graph still contains the affected package.
The maintainer tracks reassessment in [Issue #13](https://github.com/driftframestudios/source-of-truth-systems/issues/13). Review a compatible patched release when one becomes available, and reassess earlier when dependency consumers, glob configuration, externally supplied pattern inputs or development-server exposure change. Keep development tooling within its intended development environment and use the production server for hosted application delivery.
[Return to the repository](#document-readme-md-b33563055168) · [General support](#document-support-md-c5fe610b0215)
## `SUPPORT.md`
Source document: `SUPPORT.md`.
# Support
Start with [Getting started](#document-docs-getting-started-md-31bcba2ccafa) for local use and [Deployment](#document-docs-deployment-md-7f6254f34e12) for Node and PostgreSQL. The [documentation index](#document-docs-readme-md-0b5ca119d2be) routes to behavior and data contracts; the [runbooks](#document-docs-runbooks-readme-md-39a19900e08a) cover repeatable maintenance and recovery.
For a question or reproducible bug, use this repository's Issues tab. Include the revision, Node/browser version, selected view and a few steps using the bundled examples. State what you expected and what happened. A short sanitized error description is usually enough to begin; keep credentials, cookies, real records and private hosting logs with their owners.
This is a solo-maintained example project. The maintainer can discuss a repair or contribution, while availability and response time vary. Hosting account access, DNS and provider service failures remain with the deployment operator and provider. A GitHub check or local build cannot establish the health of a separately deployed instance.
Use [Security](#document-security-md-f6ed156e4bf5) for a sensitive finding and [Contributing](#document-contributing-md-eca12c0a30e2) to propose a change. Repository discussions follow the [conduct policy](#document-code-of-conduct-md-ffdbe3a1e7ee).
[Return to the repository](#document-readme-md-b33563055168)
## `docs/README.md`
Source document: `docs/README.md`.
# Documentation
Use the application to explore synthetic life sciences workflows, then follow the route that matches what you want to build or understand. The Markdown files here are the current documentation source. The ordinary build also serves selected articles at `/docs/`; the same source can build at the root of the independent foundation site. [Documentation implementation](#document-docs-site-implementation-md-994b21e246e5) names the manifest, profiles and source-derived GraphQL reference.
## Start and try
- [Getting started](#document-docs-getting-started-md-31bcba2ccafa): local example, a sample walkthrough, Node API and one focused test.
- [Fixture provenance](#document-docs-fixture-provenance-md-8ff275b9c7d1): synthetic records, supplied findings and scenario-policy boundaries.
- [Database choices](#document-docs-database-choices-md-a44edbfece29): supported PostgreSQL and bundled examples, with retained MySQL compatibility, plus optional graph/RDF/object-store extensions.
- [Local PostgreSQL clone](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277): start, stop, backup, restore and reset an isolated persistent example.
- [PostgreSQL](#document-docs-postgresql-md-a7cc27814ec8): server configuration, explicit schema/seed ownership, bounded transactions and recovery.
- [Deployment](#document-docs-deployment-md-7f6254f34e12): ordinary Node serving, isolated PostgreSQL, bundled examples and the Figma Make adapter.
## Change and extend
| Reader task | Source route | Related contract |
| --- | --- | --- |
| Add a scene or preserve edits across responsive views | [Application](#source-27d865c285d9) | [Mobile](#document-docs-mobile-showcase-md-a1c532f6fcd0), [workspace layout](#document-docs-workspace-layout-md-b161445e3297), [loading](#document-docs-loading-experience-md-9fbe539c61fa) |
| Add a read or inspect persisted data | [Server](#source-93e4a5263a59) | [GraphQL](#document-docs-graphql-read-api-md-03dad145256f), [catalog](#document-docs-persistent-data-md-115c93b26848), [visitor workspaces](#document-docs-visitor-workspaces-md-49294a63218a) |
| Change permissions or a shared record shape | [Shared contracts](#source-8e14ddd6c044) | [Permission scenarios](#document-docs-permission-scenarios-md-cbea28e234a3), [input boundaries](#document-docs-research-input-boundaries-md-c7dbe8e1d24d) |
| Choose a useful test or investigate a failure | [Tests](#source-dacac2ebf979) | [Automation](#document-docs-development-automation-md-c3633dd085ca), [selective checks](#document-docs-runbooks-selective-check-delivery-md-0b5f34c348ca) |
| Deliver, maintain dependencies or recover setup | [Runbooks](#document-docs-runbooks-readme-md-39a19900e08a) | [Node deployment](#document-docs-deployment-md-7f6254f34e12), [publication scan](#document-docs-runbooks-publication-scan-md-2fd2d22ef3bb), [database recovery](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) |
## Understand an interaction
[Specimens](#document-docs-specimen-table-md-cd6b2fe720d6), [Source records](#document-docs-source-discovery-md-40a2d04884a2), [comparisons](#document-docs-comparison-decisions-md-3003b90861d1), [release records](#document-docs-release-workflows-md-9eebdfbf2768), [Map and QC](#document-docs-operational-workflows-md-f6abb8b89c02), [Artifacts](#document-docs-artifact-operations-md-7ff5ea1a7629), [Cohort rules](#document-docs-cohort-rules-md-bacccc83d4fa) and [Profile](#document-docs-profile-preferences-md-96585d17da7a) name their accepted effects and recovery. [The workspace assessment](#document-docs-workspace-audit-md-c4b571428b60) connects these families without treating every visible control as an external operation.
[Theme](#document-docs-theme-contract-md-9253d68c555a), [Plate layout](#document-docs-plate-workspace-md-14d2cf5280a5), [compact records](#document-docs-compact-records-md-8c3453ea976e) and [presentation styles](#document-docs-presentation-styles-md-b2f82a4fd1a5) describe composition and paint. [Shareable navigation](#document-docs-shareable-navigation-md-bcfb7b016c1b) records bounded URLs, Back/Forward and Source draft continuity. [Guided exploration](#document-docs-research-guided-exploration-md-ad62b036d202) explains the optional walkthrough's control handback. Research documents preserve the source and reasoning behind a decision; their dated observations stay distinct from a check of a new revision.
## Source and publication
Edit an owning Markdown document rather than generated output. The ordinary build generates `/llms.txt` and `/llms-full.txt` from the population in [the content manifest](#source-d49fc7030a43): root Markdown, `LICENSE`, `docs/`, `guidelines/`, `.agents/skills/`, admitted articles and the generated schema reference. That public bundle includes development guidance; it grants no runtime authority. Nearby READMEs under source directories remain repository reading routes, linked from this index. [Attributions](#document-attributions-md-5138861280db) and [the license](#document-license-c693279643b8) retain their own roles.
Human and AI-assisted contributors can use the local methods in [AGENTS.md](#document-agents-md-a54ff182c7e8). Required operating guidance lives in this clone; public research references supply additional context.
[Return to the repository](#document-readme-md-b33563055168)
## `docs/artifact-operations.md`
Source document: `docs/artifact-operations.md`.
# Artifact checks and revision proposals
Artifacts keeps the recorded files and their acceptance findings readable while visitors inspect local references and prepare a revision proposal. Gallery, Lineage and Comparison consume the same browser-session records. Reload starts from the supplied examples.
**Check local references** validates the title, type, release and revision, then resolves each `derivedFrom` entry against the accepted source records and original artifacts. A missing, empty or self reference produces a concrete failed check. The result describes the locally available metadata at the time of the check; run it again after source changes. Recorded scientific and visual acceptance findings retain their own status and notes. The comparison matrix derives its cells from those same findings; a dash means the finding was not recorded.
**Prepare revision** creates one metadata proposal linked to its original artifact. Visitors can edit the proposal title and planned change, save it for this browser session, or discard it and prepare again. The original title, revision, content hash, file size and acceptance evidence remain the record of the supplied file. File rendering and external build execution remain separate future operations.
`artifactWorkflows.ts` owns validation, typed commands, current permission checks and expected-revision checks. `artifactWorkflowContext.ts` initializes the feature lazily within the existing browser-session owner. Checks require `analysis.run`; proposal preparation, saving and discard require `workspace.edit`. Commands resolve their own canonical artifact and current source collection before accepting an operation. Other artifacts retain their existing state.
The focused unit contract observes broken/current references, retained evidence, proposal recovery and refused operations. The browser journey observes all three projections, navigation retention and read-only refusal. The ordinary Node build remains the delivery route.
This contract supersedes the earlier unavailable Regenerate / Re-run checks controls with named local operations. The application describes metadata preparation as a proposal rather than as a generated file.
## `docs/cohort-rules.md`
Source document: `docs/cohort-rules.md`.
# Cohort rules
The Cohort Builder saves named rule definitions for the current browser session. Visitors reopen a saved rule, update it, save a separate copy, or remove it. Removing a saved rule leaves its open draft available for recovery. Navigation and desktop/mobile layout changes preserve the saved collection; reloading the page starts a fresh collection.
This shared owner supersedes the earlier view-local rule snapshots. The palette, nested AND/OR/NOT canvas, result cards and compiled reading rail retain their visual roles. **Rule expression** describes the readable expression; the application evaluates its typed definition locally. A saved rule contains its name and predicate tree. Specimen records and result counts remain projections of the current accepted records.
## Ownership and acceptance
- `services/cohortRules.ts` owns the rule types, facet value catalog, bounded validation and current-record projection. Biomarker lookups are grouped by specimen once per accepted record snapshot.
- `services/cohortSession.ts` owns create/update/remove commands. Each command checks the current `workspace.edit` permission. Updates and removals require the revision the visitor opened; a stale draft remains available to save separately or replace by reopening the saved version.
- `services/cohortSessionContext.tsx` creates the feature resource in the existing browser-session owner. Its lifetime is independent of a mounted Cohort view. The feature adds no SQL writes, providers or deployment dependencies.
- `BooleanBuilderView.tsx` owns the editing draft and its focus/selection. It reads accepted specimens and biomarkers through the existing record projections. Order workflow and Biomarker review facets respond to accepted workflow edits; Pipeline stage continues to describe the bundled pipeline stage.
Acceptance copies only owned definition fields and validates names, group labels, unique node IDs, supported facet/value pairs, joiners and nesting. The limits are 120 characters per rule name, 100 per group label, 128 cards and eight nested levels. Draft operations apply the card/depth bounds before recursive rendering, matching or expression building. A rejected addition retains the existing canvas and explains how removing a card or unlinking a group makes room. Editable labels remain flexible until Save applies the full definition contract. A refusal preserves both the accepted collection and the visitor's open draft.
## Matches and consent
The canvas, palette and saved-rule cards calculate from the same current records. **Matched** includes every record satisfying the definition. **Eligible** includes only matching records with active consent. **Consent-held** counts pending, rescinded and expired records separately. These records remain inspectable in the example result cards and stay outside the eligible cohort, including when the rule uses OR or negates consent. No patient-data export is implied by saving a definition.
## Evidence and continuation
`tests/cohort-session.test.mjs` exercises retained definitions, independent updates/removals, revision conflicts, current role/environment checks, malformed trees, accepted specimen/biomarker changes and consent partitioning. `tests/browser/cohort-rules.spec.mjs` observes save/reopen/update/copy/remove, a specimen hold changing a saved rule's count, responsive retention, a denied save retaining its draft, and reload reset. The existing metric comparison checks retain the explicit at-least/at-most target contract.
Durable user identity and server-owned rule storage remain separate receiving work. The existing Node server and stored-history paths retain their owners.
## `docs/compact-records.md`
Source document: `docs/compact-records.md`.
# Compact record workspaces
Cohort Builder and Artifacts keep the primary task readable at compact desktop widths while retaining their established wide layouts. The [Cohort](#document-docs-cohort-rules-md-bacccc83d4fa) and [Artifact](#document-docs-artifact-operations-md-7ff5ea1a7629) contracts continue to own accepted operations.
## Composition decision
Persistent rails support comparison on wide screens. On a compact workspace, two Cohort rails squeeze the editable rule between them; a fixed Artifact inspector similarly compresses every gallery card. Smaller text would preserve those constraints, and a modal drawer would cover the record context. The receiving layouts instead use two bounded patterns:
- **Cohort:** below 1280px, one supporting rail switches between **Add cards** and **Rule & saved** beside the main editor. Matched, eligible and consent-held counts stay visible above the canvas. Saving a rule reveals its saved receiver. At wider sizes, the original left palette and right compiled rule remain visible together.
- **Artifacts:** below 1280px, selecting a gallery card gives that record the full working area. A fixed header keeps its title, release, revision and **Back to gallery** visible. Local revision/check controls sit beside the original acceptance and provenance material. The wide layout retains the three-column gallery and side inspector. Returning focuses the selected card.
Cohort tools and the Artifact gallery remain mounted while their compact alternatives are shown. Resizing changes composition through CSS rather than replacing editors, so an untouched editing draft retains its values. Explicitly leaving an editor retains the existing draft lifetime; accepted rules, proposals and check results remain with their browser-session owners.
## Source ownership and evidence
`cohort-builder.css` owns rail placement, compact tool states and the wrapping compiled-reading viewport. `artifact-workspace.css` owns gallery/detail geometry and the wrapping record viewport. Both consume existing theme roles. The comparison matrix retains its intentional horizontal pan. Mobile continues to use the dedicated Corridor/Plate workspace.
`tests/browser/compact-records.spec.mjs` observes usable primary-area width, rail selection, saved-rule return, draft retention across desktop widths, and Artifact return focus. Existing Cohort and Artifact journeys retain save/reopen/update/remove, proposal/check, refusal and responsive acceptance evidence. The Cohort containment cases reveal the compact rule rail before checking its full expression, consent and saved records. Settled before/after captures at 1024×768 and 1512×982 provide the visual comparison; interaction tests establish behavior separately from those images.
## `docs/comparison-decisions.md`
Source document: `docs/comparison-decisions.md`.
# Comparison decisions
Comparisons lets a visitor accept a displayed resolution, keep a comparison for later review, or reopen a settled item. The two source statements, their authority states and the resolution text remain visible beside the accepted status.
## Interaction and visual contract
| Current status | Available action | Result |
| --- | --- | --- |
| Pending or Conflict | Resolve | Resolved; accepts the displayed resolution |
| Pending or Conflict | Defer | Deferred; retains the proposal for later review |
| Deferred | Resolve | Resolved |
| Resolved or Deferred | Reopen | Pending; returns the item to review |
The summary includes all four statuses and reads the same accepted collection as the cards. Mode filters affect the displayed cards; they leave accepted decisions intact. Section navigation restores the latest decisions. The application session retains accepted decisions through desktop/mobile replacement, alongside specimen and biomarker edits. A full reload starts a fresh example session. The deferred comparison provider keeps its command policy and consumes a lazy session-owned state cell.
The existing paired evidence cards, compact actions, status colors and release identity remain. Header groups wrap at compact laptop widths, and the card list scrolls inside the workspace. Resolved records offer Reopen; Pending, Conflict and Deferred retain a proposed-resolution label. The updated status is an inline live result rather than an extra form or blocking dialog.
## State and command ownership
`services/comparisonSession.ts` owns the ordered ID index, explicit transition table, immutable updates and status summary. An accepted update replaces only its target record; source fixtures and other records retain their identity. Missing IDs, repeated decisions and unavailable transitions preserve the state object.
`comparisonSessionContext.tsx` keeps the collection above desktop section navigation. It exposes records and a `decide` command, while retaining the setter privately. Every command evaluates the current shared write gate at this owner. Refused actions display the existing permission explanation and preserve the accepted record. The pure transition function also requires a permitted result, keeping the effect boundary explicit for later command-policy work. The view uses the same gate for its role and affordance display.
This is a browser-session decision over the provided comparison. It leaves the separate Decision Log, source content and server data under their existing owners. Persistence and wider command enforcement can extend this boundary through the dedicated work items; clicking Resolve does not publish a source change.
## Evidence
`tests/comparison-session.test.mjs` proves target identity, immutable fixtures, retained resolution text, legal reopen/deferral paths, summary agreement and unchanged state on denied or invalid commands. `tests/browser/comparison-actions.spec.mjs` exercises Resolve → filter → Reopen → Defer → section return → Reopen, verifies another record remains Pending, and checks a Production refusal plus compact-width containment. Production Chromium and type checking establish these receiving paths; hosted persistence is outside the browser-session contract.
## `docs/database-choices.md`
Source document: `docs/database-choices.md`.
# Choose a database for an adaptation
The public edition uses PostgreSQL for its persistent synthetic example and retains a bundled-example route for immediate exploration. The source implements the catalog and visitor-workspace adapters; the [isolated Compose clone recipe](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) provides the complete receiving setup. [PostgreSQL setup](#document-docs-postgresql-md-a7cc27814ec8) documents the executable native route and its recovery boundaries.
Public setup and release acceptance focus on PostgreSQL and generic Node hosting. Each clone owns its own records and credentials. The source also retains a MySQL adapter for explicitly selected compatibility work.
## What runs today
| Route | Behavior in the current source | Receiving owner |
| --- | --- | --- |
| Vite source development | Bundled records and browser-local workflow edits; this process does not host either GraphQL API | [Getting started](#document-docs-getting-started-md-31bcba2ccafa) |
| Node with database settings absent | Scoped GraphQL reads over the synthetic baseline; Source edits remain local to the browser session | [Server](#source-93e4a5263a59) and [configuration](#source-1a24ec4051db) |
| Optional compatibility: Node with complete MySQL settings and explicit setup | Stored Plate, well, result and file metadata; an independently installed workspace schema can retain bounded Source metadata edits | [Stored data](#document-docs-persistent-data-md-115c93b26848), [visitor workspaces](#document-docs-visitor-workspaces-md-49294a63218a) |
| Node with explicit PostgreSQL settings and setup | The same stored Plate and expiring Source contracts through PostgreSQL 18 | [PostgreSQL](#document-docs-postgresql-md-a7cc27814ec8) |
| Incomplete settings or an unavailable configured database | A visible configuration or stored-data failure; the server preserves that failure instead of silently substituting examples | [Read API](#document-docs-graphql-read-api-md-03dad145256f) and [workspace storage](#document-docs-workspace-storage-md-c97549ad8a50) |
Complete `DB_*` settings select the retained MySQL adapter. `DATABASE_PROVIDER=postgres` with complete `PG*` settings selects PostgreSQL; mixed or incomplete configuration receives an explicit error. The current Source store saves title, description and tags with revision checks, exact retry receipts and bounded history. Other accepted workflow edits retain their browser-session owners. File records describe object identities and locations; the application does not currently upload or retrieve assay binaries.
GraphQL is the application's typed API boundary. It can resolve relationships from relational tables, a property graph or another owned adapter. Its presence alone creates neither a graph database nor an ontology.
## Start with PostgreSQL for persistent examples
PostgreSQL fits the first adaptation because the existing operations already depend on explicit identities, related records, constrained updates and transactional acceptance. Keep frequently joined or filtered identities and ownership fields in ordinary columns with keys and constraints. Use bounded `jsonb` fields for variable metadata when their actual reads justify that shape; choose targeted indexes after inspecting those reads. PostgreSQL documents both `jsonb` containment/indexing and its differences from byte-preserving `json`. A JSON document remains subject to the application's schema and size checks. [PostgreSQL JSON types](https://www.postgresql.org/docs/current/datatype-json.html)
The PostgreSQL adapter implements the existing read and command contracts. [Canonical seed preparation](#source-d95e72141ac1) is shared across engines; dialect-specific schema, locks and transactions retain explicit owners. Repeat setup preserves accepted data, and normal startup reads the installed schema. [The adapter contract](#document-docs-postgresql-md-a7cc27814ec8) records snapshot isolation, cleanup, type normalization and tested failure/recovery paths.
For local operation, the reviewed Compose recipe keeps the database on its internal network and publishes the app on loopback. Each checkout receives a random project identity, private generated credentials and a named volume, including checkouts whose directories share a basename. Startup waits for database health and explicit schema/seed validation. Separate stop, backup, restore and confirmed reset commands make their data effects visible. [Local operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) owns the tested commands. [Docker database seeding](https://docs.docker.com/guides/pre-seeding/) supplies background on fresh-volume initialization.
Carry the Source workspace contract across engines: opaque cookie authority, origin and expiry scope, current permission checks, expected revision, idempotency identity, atomic projection/history writes, quotas and explicit reset. Keep idempotency fingerprints tied to the shared normalized command representation; `jsonb` key ordering must not become their authority. A stored workspace is a bounded sandbox for synthetic edits, not a verified clinical identity. [Workspace contract](#document-docs-visitor-workspaces-md-49294a63218a)
## Add a graph only when traversal earns it
A property graph can help when the receiving question follows several kinds of relationships—for example, from a sample through derived files, analyses and decisions—and the required paths vary across investigations. PostgreSQL remains a reasonable starting point for fixed joins and bounded recursive queries. Evaluate a separate Neo4j projection only when representative traversal queries, update ownership and measured execution make its extra service worthwhile.
The Neo4j GraphQL Library can derive a GraphQL API and translate operations to Cypher. Its generated API would be an explicit adaptation, not a replacement for this application's finite approved operations. Any integration must carry current identity, consent, geography and workspace scope into both direct and nested reads, bound traversal cost, and retain the command owner for writes. Choose whether relational records remain authoritative and how the graph catches up before introducing a second writable copy. [Neo4j GraphQL Library](https://neo4j.com/docs/graphql/current/)
## Use RDF for shared meaning and interchange
RDF is a different extension: named relationships and shared vocabularies can connect an assay, organism, provenance record or external identifier across independently maintained systems. RDF represents statements as triples and uses IRIs for identity; vocabularies supply agreed terms. That can serve ontology alignment or interchange even when transactional application records remain relational. [W3C RDF primer](https://www.w3.org/TR/rdf11-primer/)
SPARQL provides the query route; add OWL ontology axioms and entailment only when the receiving task needs those inferences. Select the supported reasoning profile and distinguish asserted relationships from inferred ones in the returned evidence. [SPARQL overview](https://www.w3.org/TR/sparql11-overview/) · [OWL 2 overview](https://www.w3.org/TR/owl2-overview/)
Choose the actual vocabulary, identifier mapping, provenance and validation rules with the receiving domain. An RDF export or bounded read projection is a smaller first step than a second writable store. Imported ontology assertions need their own provenance and versioning; an inferred relationship does not establish a person's authorization to read its underlying records. This repository currently provides neither an RDF adapter nor a SPARQL endpoint.
## Keep assay objects outside the transactional rows
Large sequence, alignment, image and report objects belong in an appropriate object store or file service. The database should retain stable object identity, version, media type, size, checksum, provenance and the governed access relationship. A storage locator is a reference, not permission to fetch the object. Resolve access at the server boundary and keep credentials and expiring signed URLs outside source fixtures, public documentation and durable audit text.
The current example's object keys and file-status records support visual exploration. A real object-store integration would also need upload/download behavior, integrity verification, lifecycle handling and a receiving access-policy check. Preserve the synthetic baseline while designing that separate capability.
## Receive the persistent clone
The adapter delivery establishes native PostgreSQL behavior with focused real-engine checks. The clone recipe adds a pinned Compose service, per-clone identity, generated local credentials, bounded readiness, and tested backup/restore/reset commands. Its acceptance includes application/database restart and retained edits in a materialized receiving overlay.
Choose hosting independently of data modeling. A local recipe establishes its tested environment; a managed host supplies its own certificate, role, backup and receiving-deployment observations. Review component licenses when adapting or redistributing the application. The repository's MIT license leaves upstream component terms with their owners. [Deployment](#document-docs-deployment-md-7f6254f34e12) and [attributions](#document-attributions-md-5138861280db) keep those decisions visible.
[Documentation](#document-docs-readme-md-0b5ca119d2be) · [Run the example](#document-docs-getting-started-md-31bcba2ccafa)
## `docs/deployment.md`
Source document: `docs/deployment.md`.
# Deploy the example
Run the complete local application with the [PostgreSQL clone recipe](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277). Its isolated app, database and explicit initializer give each clone its own synthetic records and expiring Source workspaces. [Database choices](#document-docs-database-choices-md-a44edbfece29) explains the supported persistence boundary; [fixture provenance](#document-docs-fixture-provenance-md-8ff275b9c7d1) explains the example data.
## Choose a route
| Route | Current capability | Operator responsibility |
| --- | --- | --- |
| Local PostgreSQL containers | Pinned app/database images, private project volume, explicit schema/seed validation and runtime role | Docker/Compose and Node 22 for the clone CLI; follow [local operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) |
| Native Node with PostgreSQL | Full static assets, GraphQL and stored histories/Source workspaces | Provision database/roles, run explicit setup, inject runtime settings, manage process and backups |
| Node with database configuration absent | Scoped GraphQL over bundled synthetic records and browser-session edits | Build and start the Node server |
| Local Vite development | Hot reload and bundled interface examples | Install the frozen dependency graph; Vite does not host the Node APIs |
| Static browser assets | Browser presentation without the Node APIs or durable workspaces | Choose that limited scope explicitly, or provide a separately configured API |
| Standalone documentation | `build:foundation` emits admitted articles at the root of `dist-foundation/` | Static publication, domain configuration and a receiving-host check |
## Ordinary Node hosting
Use the declared Node 22.x and pnpm versions. From the reviewed source:
```sh
pnpm install --frozen-lockfile
npm run build
PORT=3000 npm start
```
The server binds the process to the host interface on `PORT`. Keep `dist/`, `build/server/`, server/shared source and required runtime packages together. The full dependency graph also contains build tools; the [Dockerfile](#source-dd2c0eb6ea5c) separates build preparation from the non-root runtime image. Publishing `dist/` alone omits `/graphql` and `/workspace/graphql`. `vite preview` is an asset preview rather than the complete application server.
For persistence, follow [PostgreSQL setup](#document-docs-postgresql-md-a7cc27814ec8) or the native route in [local operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277). An ordinary database-owning setup login initializes the catalog and workspace schema. A distinct runtime login receives bounded data privileges. Normal application startup reads existing records; schema changes remain explicit operator work. The complete absence of database settings selects bundled examples. Partial settings and configured storage failures retain their visible failure state.
A remote operator owns HTTPS termination, process lifetime, network restrictions, database TLS and backups. The local clone recipe binds the published app port to loopback. The native Node server listens on its host interface, so use a firewall or reverse proxy for the intended audience. Local serving checks establish HTTP, source-file exclusion, finite GraphQL operations and startup behavior; they leave provider proxy, certificate and backup behavior for that provider's check.
Review [site metadata](#source-84ad7a0a9674) before publishing a clone. Set the canonical `url` and social image for the intended origin. The build enables indexing and publishes selected documentation at `/docs/`, `/llms.txt` and `/llms-full.txt`; review those sources as public content. After deployment, observe one built asset, the mobile Corridor, Plate C3 and any installed workspace. Record the deployed source revision beside that result.
## Source development and Figma Make
`npm run dev` and `npm run dev:source` run Vite with hot reload. The source retains [.figma/make](#source-3ff219a7fa6e), [.mise.toml](#source-1bac9641068b) and [the Vite adapter](#source-ef189d75061e) for asset resolution, metadata and preview configuration. A fresh Make session owns its install/preview/import verification. Its existing static deployment script does not establish a Node GraphQL process. The root package and frozen lockfile remain the dependency owners.
## Recover and continue
Preserve the previous reviewed source or image for application rollback. A source rollback leaves database records intact. The [clone runbook](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) supplies bounded stop/start, trusted backup restore and confirmed reset; another host supplies its own recovery process. Keep credentials, database dumps and browser cookies with their private owners.
Application delivery, schema setup, repository visibility and documentation-site publication are distinct actions. Copied workflows do not copy account settings, secrets, DNS or protection policies. [Automation](#document-docs-development-automation-md-c3633dd085ca) names current checks; a successful test supplies evidence for its selected behavior and does not publish the application.
[Documentation](#document-docs-readme-md-0b5ca119d2be) · [Repository](#document-readme-md-b33563055168)
## `docs/development-automation.md`
Source document: `docs/development-automation.md`.
# Development automation
Select the smallest check that establishes the intended behavior. Verify change receives every main PR with its fitting docs or Core route. Browser, real database and publication inspections remain deliberate choices. [Runbooks](#document-docs-runbooks-readme-md-39a19900e08a) connect those results to independent review and handback.
## Select a check
Optional check workflows expose `run_checks`, defaulting to `true`; Verify change always executes its selected route. Select `false` to skip a check's whole job before runner and service allocation. A skip records selection, while behavior remains unobserved. Documentation preflight always executes its selected build; its separate activation workflow uses `activate_deployment`, defaulting to `false`.
| Action | Trigger and selection | Result and boundary |
| --- | --- | --- |
| [Verify change](#source-8099043ed894) | Every main PR, including drafts and retargeting edits. Manual execution always selects Core. | Selected docs/Core checks plus complete committed-tree scanning, with a strict final outcome receiver under the [protected review contract](#source-f32a9eda0632). |
| [Core checks](#source-c1fe30b1660d) | Optional manual dispatch. | Frozen installation, types, 3D guard, build and ordinary unit/API/startup checks. Real database tests retain their explicit opt-ins. |
| [Browser checks](#source-6e38712472f0) | Manual `scene-smoke` or `all`; optional `include_core`. | Smoke uses runner Chrome when present; all uses locked Playwright Chromium. Selected production-build journeys, with optional Core sharing one install/build. Stored-workspace cases need their separate disposable database setup. |
| [PostgreSQL clone proof](#source-8ab7cc430f4a) | Manual only, for storage/clone changes or a release receiver. | Two temporary PostgreSQL projects on runner-owned Docker; stored reads, isolated edits, restart, backup/restore, reset and outage recovery. |
| [Optional MySQL compatibility proof](#source-04bbbd5fdb96) | Manual only for a change to the retained adapter. | Ephemeral MySQL 8.4 catalog/import, workspace transactions and HTTP behavior. This is compatibility evidence, not the public PostgreSQL deployment route. |
| [Publication scan](#source-6cf50cec3027) | Manual source/history/release selection; Verify change owns automatic main-PR scanning. | Pinned detector, fresh canary and sanitized identity/result for selected source or built artifacts. Metadata, rights and visibility retain their own receivers. |
| [Documentation preflight](#source-107c0b32e403) | Manual, from main, for exact accepted app/docs revisions and an immutable documentation tag. | One foundation build, checked routes and file manifest, fresh-canary artifact scan and a retained release receipt. |
| [Activate documentation](#source-192089dc8012) | Manual, from main; explicit activation defaults off. | Verifies the reviewed preflight artifact and deploys those same files through the main-only Pages environment. |
For a shared dependency or release candidate, select Browser `suite=all` and `include_core=true`. These checks share installation and build inside that job. Select actual PostgreSQL proof separately through the [native populations](#document-docs-postgresql-md-a7cc27814ec8) or the [two-clone Compose proof](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277). The manual PostgreSQL workflow invokes that same Compose proof on runner-owned Docker; it generates and cleans up its own project identities.
Manual Actions use the selected branch/tag; compare the run commit with the reviewed revision. Documentation release Actions additionally require the protected main receiver and exact accepted source coordinates. Automatic PR checks use GitHub's proposed merge revision. New source earns fresh evidence for affected behavior. Required Verify change has no PR path filter; it selects its observation inside the job. The active docs-branch check uses pinned main tooling. The receiving repository's Pages source is Actions, with explicit [tagged artifact activation](#document-docs-runbooks-tagged-documentation-release-md-33af7f4666be); copying workflow files alone installs no account settings.
## Preparation and execution
The shared [prepare action](#source-a9d4fab00e8a) reads Node/pnpm from the package, restores the lockfile-keyed package store and performs a frozen installation. Separate jobs receive separate environments. Selected Browser steps reuse one installation/build. Package caches provide dependency bytes, not previously accepted build or test results.
Scene smoke records runner Chrome's version, or installs locked Chromium when Chrome is absent. The full suite uses Playwright's matched browser and Linux dependencies. One worker, zero retries and an owned production server on port 3200 keep lifecycle clear. Desktop preset/Reset motion-phase checks use a controlled Playwright clock and actual DOM transforms; perceived smoothness retains a separate real-time observation.
PostgreSQL checks require an independently provisioned disposable loopback database and explicit `POSTGRES_TEST=1`; use separate invocation-owned databases for destructive catalog/workspace populations. Compose proof owns temporary projects and exact-project cleanup. The optional [MySQL runner](#source-a65b7b4c6772) requires disposable `sot_*_test` or `sot_*_proof` settings, a fresh build and MySQL CLI, then sets child opt-ins and sequences destructive storage, initialization and HTTP checks. Run it with `npm run test:mysql`. A loopback address alone cannot establish that a tunnel leads to disposable data; verify ownership before either engine route.
## Recovery and delivery
A newer selected check cancels older work in its workflow/trigger group. A skip dispatch has a separate concurrency group and preserves an active check. Documentation preflights retain their own run identities; Pages activations serialize without cancelling an in-progress deployment. A failed phase keeps its result visible; repair the named owner before rerunning. Registry and runner outages remain incomplete observations. Raw browser traces, screenshots and scanner reports stay with private/local diagnostic owners.
Publish only after the intended revision has its fitting checks, independent review and authorization. [Deployment](#document-docs-deployment-md-7f6254f34e12) supplies the ordinary Node/container boundary; [local operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) owns trusted backups and confirmed reset. Application rollback and database recovery are separate actions. Check success preserves the existing publication; explicit Pages activation deploys the selected static artifact. Repository visibility remains a separate owner action.
Check and build jobs use read-only repository tokens and unprivileged PR execution. The isolated Pages deployment job holds `pages: write` and `id-token: write` under its main-only environment. External actions are pinned; hosted database credentials stay outside these routes. The MySQL service password is a disposable fixture. Inputs reach bounded environment/action parameters without shell evaluation. Before updating an action, verify its release commit and update the SHA/comment together. A changed workflow earns an explicit exercise of its affected route. Compare preparation/build/execution cost before adding cache or parallel-job machinery.
[GitHub workflow security](https://docs.github.com/en/actions/reference/security/secure-use), [path-filter behavior](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetpathspaths-ignore), [runner environments](https://docs.github.com/en/actions/concepts/runners/github-hosted-runners), and [Playwright CI preparation](https://playwright.dev/docs/ci#caching-browsers) ground the current controls. Actual runs establish results for their named source; this policy supplies no measured performance claim.
## `docs/display-vocabulary.md`
Source document: `docs/display-vocabulary.md`.
# Display vocabulary
Visitors explore **Source of Truth for Life Sciences** through genomic workflows, named source records, and release planning. The Release plan connects delivery requirements, source evidence, review criteria, and deferred work. Its summary is a read-only projection of the current sample plan; publishing remains visibly unavailable.
`src/app/services/cartographyService.ts` owns release, source-role, authority, and reference display helpers. Receivers resolve a record within its named collection before showing its title. Sources and artifacts can share a baseline identifier, so cross-record navigation retains both the section and identifier. The generic lineage helper gives the shared source baseline its source title; it does not choose navigation targets.
| Visitor language | Stable internal representation |
| --- | --- |
| Release plan | `next-arc` route, `generationPacket` |
| Release 01 / 02 / 03 | `arc_01` / `arc_02` / `arc_03` |
| Revision | artifact `pass` |
| Requirements | `instructions` collection and instruction IDs |
| Program context | `loam_context` source role |
| Genomics program brief | `notion_fragment` source ID |
These display changes preserve relationships, access roles, stored records, and routes. Technical terms such as LIMS, AWS Batch, VPC, FASTQ, and ECR remain where they identify the work. Git history retains the retired import material and corridor reference image. Sample descriptions describe genomics delivery and infrastructure; they do not initiate vendor fetches or deployments.
`ShowcaseCredit` supplies the mobile About footer and the planned Welcome footer. It carries the confirmed 2026 copyright holder and creation-tool credit, including the owner-confirmed Claude Opus 5.5 and GPT-6 Astra versions. The repository's MIT license remains unchanged.
Checks cover collection-specific title resolution, a summary derived from the supplied plan, desktop/mobile linked-record return paths, release preview behavior, and mobile About content. Presentations consumes the same release helper in its separately reviewed rendering work.
## `docs/fixture-provenance.md`
Source document: `docs/fixture-provenance.md`.
# Example data and reuse
The bundled examples help visitors explore genomics workflows, sample histories,
provenance and resource decisions. The repository combines generated plate data
with curated scenario records; it loads these examples from source rather than a
live laboratory system.
| Example family | Source and purpose |
| --- | --- |
| Plate wells and result histories | [Application data](#source-f09b34f83e85) and [well results](#source-93d2d99a42d4) generate repeatable values from fixed seeds and supply curated rerun, recovery and storage stories. |
| Specimens, biomarkers and workflow records | [Application data](#source-f09b34f83e85) supplies scenario findings, evidence labels, therapy associations and review states for exploring the interface. Scientific names retain their ordinary meanings; the supplied associations belong to these examples. |
| People, roles and access | [Access examples](#source-5b803a8f212c) use reserved `.example` addresses and scenario grants. Consent and data-class labels exercise policy behavior; verified identity and actual record provenance require their own implementation. |
| Server responses | [Server example data](#source-11f8c64ec9a8) projects the same collection for the GraphQL example adapter. Hosted history and disposable-workspace adapters have separate persistence owners. |
Regional key/residency explanations, the ten-year retention entry and release
signature checkpoints describe the scenario's organizational assumptions. They
are not general regulatory requirements or compliance determinations. Operational
reuse calls for organization-reviewed policies and independently validated
scientific findings.
Cloud bucket labels, masked account references and storage locations depict an
example infrastructure arrangement. Provisioned environments supply their own
coordinates and server-side credentials. Stable legacy identifiers connect
records and accepted edits; their wording carries compatibility meaning rather
than a dependency on an earlier workspace.
To extend the examples, edit the owning source collection and check its related
record, policy and rendering behavior. Keep real patient records and credentials
in an appropriately governed system; this repository's fixtures support
interaction and implementation exploration.
[Return to the repository guide](#document-readme-md-b33563055168).
## `docs/getting-started.md`
Source document: `docs/getting-started.md`.
# Run and explore the example
Each clone can run its own PostgreSQL-backed synthetic example. Plate history and expiring Source metadata survive restarts; other workflow edits retain their browser-session lifetime. [Fixture provenance](#document-docs-fixture-provenance-md-8ff275b9c7d1) explains the supplied findings and policy assumptions.
## Start the complete local application
Use the steps below with a repository clone. If GitHub requests access, ask the maintainer for an invitation. You can also explore the [live application](https://kindlight.ai) directly.
Install Git, Node **22.15 or newer within 22.x**, and Docker with Compose. From the clone's root:
```sh
node scripts/clone.mjs configure --port 3000
node scripts/clone.mjs up
```
Open `http://localhost:3000`. The build installs locked dependencies, creates this clone's private configuration and isolated database volume, initializes canonical examples, and starts the app after schema validation. Host pnpm is optional for this route. Select another loopback port during configuration if needed.
Open Plate → Sample history and select C3 to see **Stored history**. In Sources, start a saved workspace, edit a title, and reload. A workspace lasts up to 24 hours and belongs to its original browser and origin. Stop/start preserves its database:
```sh
node scripts/clone.mjs stop
node scripts/clone.mjs up
```
[Local clone operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) covers readiness, separate Docker contexts, two clones, backups, restore, reset and an existing native PostgreSQL server. [Database choices](#document-docs-database-choices-md-a44edbfece29) explains the storage decision and extension options.
## Start the local interface
Install Node **22.15 or newer within 22.x** and pnpm **10.34.3**. [package.json](#source-7ae45ad102ea) and [.mise.toml](#source-1bac9641068b) declare the supported toolchain. From the clone's root:
```sh
pnpm install --frozen-lockfile
npm run dev:source
```
Open `http://localhost:8443`, or the URL printed when you deliberately set another `PORT`. The server uses a strict port; if 8443 is occupied, stop that owned process or run `PORT=8444 npm run dev:source`. Stop this server with Ctrl+C when finished.
`dev:source` runs Vite with hot reload. It uses bundled example records and local Source edits, without installing a database or starting the production GraphQL routes. Reload returns local workflow edits to their example state; appearance and the first-invitation preference have separate browser storage. Use the Node route below to inspect actual API behavior.
## Follow a sample
Open **Guide** in the header and choose a question or **Watch walkthrough**. Watch the three scenes or select a question and explore at your own pace. Taking control or closing the guide leaves the current scene available.
For direct exploration, open Plate and select C3. Compare the results and related files in Sample history. C3's example distinguishes reanalysis of existing reads from a later confirmation; the displayed history supplies the details. On mobile, the Corridor and Plate use compact controls and record panels. Resizing retains the selected scene and sample.
## Run the Node API locally
Leave `DATABASE_PROVIDER` and database-specific `DB_*`/`PG*` settings absent for the bundled example adapter. A partially configured database produces an unavailable stored read, rather than silently selecting examples. Ordinary startup does not automatically read a local `.env` file.
```sh
npm run build
PORT=3000 npm start
```
Open `http://localhost:3000`. The build creates public `dist/` and private `build/server/`; keep both together with the server source. `scripts/serve.mjs` exposes the two GraphQL routes and serves only the intended public directory. The no-database deployment keeps Source edits local. [GraphQL reads](#document-docs-graphql-read-api-md-03dad145256f) includes a complete approved-query request; [visitor workspaces](#document-docs-visitor-workspaces-md-49294a63218a) describes optional expiring Source persistence.
This Node route also serves [the developer documentation](#document-docs-site-implementation-md-994b21e246e5) at `http://localhost:3000/docs/`. The app's **Developer docs** link opens it separately while preserving current work. The Vite source-development process above remains the lighter interface-only route.
This is a production-like local process, not a public deployment. Stop it with Ctrl+C. [Deployment](#document-docs-deployment-md-7f6254f34e12) describes hosting, optional database setup and recovery.
## Try a focused check
After dependency installation, run:
```sh
npm run test:mobile
```
This source-owned Node test exercises Corridor pointer ownership, pinch and release behavior. It needs neither a production build nor a browser installation. It establishes gesture behavior, while a layout change still needs a visual/browser observation. [The test guide](#source-dacac2ebf979) routes to other owners and the complete build-dependent suite.
## If startup needs attention
| Observation | Next action |
| --- | --- |
| Unsupported Node or package-manager version | Use the declared 22.x/pnpm toolchain, then repeat the frozen install. |
| Frozen install rejects a changed dependency graph | Inspect the root package and lockfile together. An intentional dependency change follows the [maintenance runbook](#document-docs-runbooks-dependency-maintenance-md-38672f828879). |
| `npm start` reports a missing projection | Run `npm run build` in the same clone before starting. |
| Stored history is unavailable | For a clone, inspect `node scripts/clone.mjs status` and `logs`; [PostgreSQL setup](#document-docs-postgresql-md-a7cc27814ec8) explains schema recovery. The bundled route needs database configuration absent. |
| Fonts are unavailable offline | System fallbacks remain usable. [Font delivery](#document-attributions-md-5138861280db) explains the external requests and a deliberate self-hosting route. |
[Documentation](#document-docs-readme-md-0b5ca119d2be) · [Repository](#document-readme-md-b33563055168)
## `docs/graphql-read-api.md`
Source document: `docs/graphql-read-api.md`.
# Corridor and Plate read API
The existing Node server now serves `/graphql` alongside the showcase. It reads the synthetic baseline or the configured Hosted MySQL catalog through a validated, request-local permission scenario. Browser edits retain their current state owner. Finite scenario selection demonstrates policy; verified private identity remains a separate boundary. The [Hosted Database guide](#document-docs-persistent-data-md-115c93b26848) owns configuration, initialization, import and recovery.
## Run a read
Use Node 22.15 or newer within the 22.x line, install the pinned dependencies, then:
```sh
npm run build
npm run graphql:operations
PORT=3000 npm start
```
The operation command prints each reviewed operation name and its SHA-256 document hash. Copy the `PlateOverview` hash into this request:
```sh
curl http://localhost:3000/graphql \
-H 'Content-Type: application/json' \
-H 'Accept: application/graphql-response+json' \
--data '{"extensions":{"persistedQuery":{"version":1,"sha256Hash":"COPY_PLATE_OVERVIEW_HASH"}},"variables":{"id":"NVSX-2026-118","first":12}}'
```
The hashes identify exact query documents. They are ordinary public lookup keys, with no authentication role and no relationship to mutable record fingerprints. Adding or changing a reviewed `.graphql` document changes the operation inventory at the next build/deployment. The server accepts the deployed inventory and has no registration endpoint.
For local schema exploration, run `NODE_ENV=development GRAPHQL_EXPLORER=1 npm start` after building. This explicit mode binds to `127.0.0.1` and enables GraphiQL and arbitrary queries. Production ignores the flag.
## Source ownership
| Owner | Responsibility |
| --- | --- |
| `src/app/data` | Canonical synthetic corridor, plate, result history, and file fixtures |
| `src/server/example-data.ts` | Build-time read projection of those same fixtures |
| `vite.server.config.ts` | Generates `build/server/example-data.mjs` outside public `dist` |
| `server/graphql/schema.graphql` | Typed query, record, enum, nullability, and connection contract |
| `server/graphql/schema.mjs` | Membership-gated workflow context and scoped Plate relationship resolvers |
| `shared/permission-scope.mjs`, `services/permissionScope.ts` | Shared policy, immutable canonical catalog, grant replay and record/field projection |
| `server/data` | Example/MySQL repositories, request connection scope and explicit schema setup |
| `shared/plate-records.mjs` | Bounded canonical record decoding shared by server and browser |
| `server/graphql/pagination.mjs` | Bounded, collection-scoped forward paging |
| `server/graphql/operations` | Reviewed production query documents |
| `server/graphql/operations.mjs` | Validated operation inventory and standard SHA-256 document identity |
| `server/graphql/api.mjs` | Yoga HTTP handling, persisted-operation plugin, request limits, and error policy |
| `scripts/build.mjs`, `scripts/serve.mjs` | Browser/private server projections and ordinary Node startup |
The baseline is loaded once per server process. Lanes follow lane order, cards follow their position, wells follow row/column order, and histories follow `sequence`. Example maps keep fixture reads direct. MySQL reads use a request-owned connection and read-only transaction, bounded queries, batched history artifacts and a request-local result cache. The scoped adapter also reuses canonical well reads within that request, keeping relation checks on the same snapshot without repeated anchor queries. Corridor reads retain the fixture source and open no database connection.
Well IDs are plate-local coordinates: pass both `plateId` and `id` to read a well. A result retains its anchor `wellId` separately from its physical run plate and well. A reused file keeps the same `File.id` object key across results; each result owns its own artifact reference and `reusedFrom` relationship. Byte sizes use `Float` because many example objects exceed GraphQL's signed 32-bit `Int`; they remain integer byte counts in the baseline.
Lookup fields return `null` when a valid ID has no record. Collections return an empty connection when their permitted projection contains no records. A known direct record outside the scope returns a tagged `FORBIDDEN` error; missing records remain distinct. Fields and references are projected before connection counts and paging. Invalid input yields a GraphQL error; unexpected adapter failures are masked in the HTTP response while the server logger retains the diagnostic. Non-null relationships express fixture invariants, so a broken owned relationship surfaces as an error instead of silently disappearing.
## Request boundaries
Production executes seven finite read documents: corridor lanes, cards, connections, plate wells, well history, result artifacts, and `PlateHistory`. The last provides a complete, bounded selected-well projection with `dataSource.mode` and `asOf`, including the current well, permitted metrics, lineage and artifact state. Its browser hash is checked against the deployed document. Other reads retain separate history/artifact paging. All documents keep selection depth fixed. Adding a document earns a review of both its relationship fan-out and its variable bounds.
| Boundary | Behavior |
| --- | --- |
| Page size | Default 20, maximum 50; operation defaults may be smaller |
| Cursor | Opaque collection-and-policy-scoped identity, maximum 512 characters; malformed or cross-scope cursors yield `BAD_USER_INPUT` |
| Lookup ID | 1–160 characters |
| Request body | 16,384 bytes, including chunked input; oversized streams receive 413 or the Node adapter closes the connection |
| Execution deadline | 5 seconds through the maintained server adapter; deadline yields 504 and aborts `request.signal` |
| Request/header receipt | 10 seconds through Node's HTTP server |
| Documents | Registered hashes only; raw queries, unknown hashes, and batched operations are rejected |
| Uploads/cross-origin client access | Multipart requests and CORS headers are disabled |
| Errors | Expected input errors remain legible; internal diagnostics stay in server logs |
Collection reads check the request signal; MySQL request scope cancels its owned transport and releases the connection in `finally`. The deadline returns a response and signals cancellation; it cannot preempt CPU-bound JavaScript. HTTP admission limits and fixed documents bound the current work without adding a general complexity engine or speculative caches.
Production requests may include `extensions.scenario` alongside the persisted query: `{ version: 1, principalId, roleId, environment, grantChanges }`. Omission selects the default Research scenario. Unsupported shapes or commands are rejected. Grant changes carry a validated actor selection, target principal, resource, geography and level; the server derives effective access by replaying them against the canonical catalog. A raw client matrix or capability claim grants nothing. The scope is immutable for the lifetime of the request.
The generic Corridor describes shared synthetic workflow and checks read capability and environment membership. Plate wells, results and artifacts use canonical geography, classification, consent and resource grants. Minimum timeline metadata stays separate from clinical text and files. [The permission contract](#document-docs-permission-scenarios-md-cbea28e234a3) owns that field policy and the distinction between explanation and analysis. The scoped repository filters before counts and paging; direct and nested references pass through the same projection. Indexed, parameterized MySQL reads and request cleanup retain their existing ownership.
The browser sends its accepted finite scenario, partitions history caches by the normalized policy scope, and cancels obsolete requests. `FORBIDDEN` suppresses fixture fallback. `OWNERSHIP_UNAVAILABLE` identifies unknown or conflicting canonical ownership and suppresses both cache and examples until a successful retry. Missing and empty histories also replace previous examples. A retryable transport/storage failure retains only currently permitted example data. Current stored-well metadata replaces its bundled counterpart together with its history.
Hosting supplies server-only database credentials. The synthetic catalog remains public showcase material; this scenario protocol establishes consistent behavior rather than verified identity. Durable writes, subscriptions, federation and AI services retain separately approved boundaries. GraphQL and MySQL packages remain server-only.
## Evidence and deployment
After `npm run build`, run `npm run test:graphql`, `npm run test:deployment`, and `npm run test:startup`. The HTTP checks cover useful scoped reads, filtered pagination and relationships, held explanations, field omission, grant replay, result/file identity, missing and empty results, rejected documents, variable/body bounds, masking, the deadline, local exploration, static/source isolation, and rebuilding both projections through the legacy hosting entry. Startup checks observe the actual emitted browser graph.
The reviewed source and frozen dependency graph produce both browser and private server projections. `npm start` fails clearly if either projection is missing. [Node deployment](#document-docs-deployment-md-7f6254f34e12) and [local clone operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) name the supported delivery and recovery routes.
## Research decision
Yoga 6.1 and GraphQL.js 16.15 provide the maintained HTTP/parser/schema layer on the supported Node 22 runtime. Yoga's persisted-operation plugin implements the reviewed-document gate; its body-size limiter counts streamed bytes; the underlying maintained server adapter supplies a request deadline. This keeps transport mechanics in maintained owners while the application owns its schema, finite operation set, and data semantics.
The decision follows [GraphQL demand control](https://graphql.org/learn/security/), [schema design guidance](https://graphql.org/learn/schema-design/), [GraphQL over HTTP](https://graphql.github.io/graphql-over-http/draft/), [Yoga production guidance](https://the-guild.dev/graphql/yoga-server/docs/prepare-for-production), [persisted operations](https://the-guild.dev/graphql/yoga-server/docs/features/persisted-operations), [Yoga's maintained release notes](https://the-guild.dev/graphql/yoga-server/changelogs/graphql-yoga), and the [server adapter's deadline implementation](https://github.com/ardatan/whatwg-node/blob/master/packages/server/src/plugins/useRequestDeadline.ts). The [GraphQL.js DataLoader guidance](https://www.graphql-js.org/docs/n1-dataloader/) describes the database batching problem; the example indexes avoid that problem, and the stored-history adapter batches artifact reads and reuses request-local result values.
## `docs/loading-experience.md`
Source document: `docs/loading-experience.md`.
# Loading and ready content
Loading uses a small horizontal plate with twelve sample discs. The discs rise and settle with staggered, gentle timing; the status names the work being awaited. Initial startup reads **Initializing system…**. A deferred module reads **Opening plate…**, **Opening linked record…**, or its existing receiving label.
## Workspace download contract
The composition borrows the existing plate edge, navy ground, teal, blue, violet and gold from semantic theme roles. It is an HTML/CSS drawing and does not load the Plate renderer, data or an animation dependency. The twelve-disc grid, rounded plate, shallow edge and fixed light direction remain consistent in the HTML and React carriers. A full startup occupies the viewport; subsequent loads stay inside their receiving workspace, with navigation available outside it.
When the actual view mounts, the plate rotates from its horizontal perspective toward the visitor. A sparse field of translucent rectangular tiles rises and recedes using the system colors. The ready reveal lasts at most 900ms; its controls are already available because the decorative overlay has no pointer capture. A fallback cleanup removes interrupted exits. There is no minimum loading duration or estimated progress. Already available deferred views skip the local loading reveal.
Reduced motion keeps the plate still and reveals ready content directly. Hidden receiving panels pause the local graphic. Failed downloads retain an explicit reload path; startup failure uses the HTML carrier before React is available. The visual describes application loading, not sample processing or a scientific result.
## Primary record companion
Sample history reserves its record tray as soon as the mode is selected, while the camera springs into place. Available record content unfurls over 240ms in parallel with the gossamer thread. Selection replaces the prior record directly; camera completion, prior-record exit and child staggering no longer gate readable content. Reduced motion reveals the record directly. The tray geometry, three scrolling columns and semantic palettes remain intact.
The tray shell owns one stable source strip above its replaceable content. Mobile uses the equivalent strip beside its record. When a selected well's GraphQL request is pending, six muted theme-colored rectangles gently change opacity. The label identifies the well and says that example history remains in view while its source is checked. The rectangles dissolve over 160ms on settlement; they never hold the content or fabricate completion percentage. The record body carries its own busy state, with the status announcement outside that subtree. Reduced motion keeps the rectangles still.
The request owner supplies `idle`, `loading`, `ready` or `unavailable`. An unread local hover is idle; a cached selection or hover is ready on its first render with its retained source. If C3 is being checked while B4 is previewed, B4 retains its own example or cached-source identity and receives no C3 loading cue. Successful empty and missing histories retain their source outcome. Failure shows the existing local Retry. The previous request is cancelled when selection changes, and its late response cannot replace the current key.
This supersedes the thread-first, sequential record reveal. Existing examples supply useful content throughout the current history check, so this implementation uses the small inline indicator. A panel-shaped geometric skeleton remains an extension for a future primary panel that truly lacks usable content. [The loading research](#document-docs-research-component-loading-md-afaef4767464) compares that option with spinners and progress bars and maps the application's other asynchronous owners. Domain states such as restore requested or rebuild queued keep their own meaning.
## Ownership and extension
- `index.html` owns first-paint markup and entry-download recovery. Keep its small grid aligned with `PlateLoading.tsx`.
- `components/loading/plate-loading.css` owns both carriers’ geometry, palette roles and finite motion.
- `components/loading/initialLoad.ts` removes the startup carrier when the receiving workspace commits.
- `components/DeferredView.tsx` retains Suspense and error recovery, and adds local waiting/ready composition. It preserves its child workspace across the reveal.
- `services/plateHistory/context.tsx` owns keyed request/cache readiness; the request helper owns abort and stale-response protection.
- `plate/PlateHistorySource.tsx` and `plate-history.css` project source, recovery and local activity from props, without fetching or inventing progress.
- `PlateScene3D`, `ResultTray` and `MobilePlate` place that projection beside the current primary record. Rendering and decorative motion retain separate lifetimes from requests.
[Guided exploration](#document-docs-research-guided-exploration-md-ad62b036d202) now presents its optional invitation after application loading and offers header replay. The guide owns its scene sequence and cancellation; loading graphics only communicate waiting and readiness.
## Evidence
The loading browser journeys hold entry/module downloads to observe waiting and cleanup, navigate away during deferred Plate loading, exercise reduced motion, and recover an entry failure. Primary-history journeys observe the tray during camera motion, local hover with zero reads, held and reversed history responses, exact well identity, cached return, retry, and mobile reduced motion. Existing download-recovery and startup-manifest checks retain mobile deferral and payload boundaries. Focused visual review covers primary-panel geometry; real network speed determines whether a visitor sees a waiting frame.
## `docs/mobile-showcase.md`
Source document: `docs/mobile-showcase.md`.
# Mobile corridor and plate
The mobile workspace lets a visitor explore a genomics workflow and inspect result histories with a few taps. Its default Dark mode preserves the navy canvas, colored corridor lanes, upright paper cards, luminous wells, and result discs from the desktop application. Light and High contrast share the same geometry, interactions and record meaning through the [theme contract](#document-docs-theme-contract-md-9253d68c555a). Example data supports a portfolio demonstration; the desktop workspace retains the broader tooling.
## Design decision
Five directions were considered: a scaled desktop canvas, a horizontally scrolling desktop workspace, a list-first browser, a full-screen scene with modal controls, and a focused scene with compact controls and a readable record companion. The last direction best combines the existing visual identity with comfortable touch targets. The corridor uses a short step rail as an alternative to selecting small 3D cards. The plate keeps its physical well board and adds the shared 3D Sample history scene; a readable result companion sits below either view so details scroll naturally in both orientations.
This supersedes the original narrow-screen projection of the complete desktop shell. Desktop source and navigation remain the authority at widths of 1024 CSS pixels and above. Below that boundary, Corridor and Plate are the two persistent navigation choices. Corridor mounts immediately; Plate loads on first selection and stays mounted afterward. Switching retains lane, camera, well, result, lens, and scroll position. Crossing the desktop boundary retains Corridor / Plate, the selected well and result, and Plate overview / Sample history with its lens, spacing and depth. Desktop Plate arrives in the compact 3D view; a mobile-first visit retains its Well board choice when returning from desktop. Explicit Corridor selection becomes the shared destination. The receiving 3D scene fits its own canvas; rotation within the mobile range keeps the mounted camera. Accepted record and comparison edits, file restores, repair deadlines, successful history reads, environment and refusal notices also survive this boundary. Reload begins a fresh browser session.
## Visual fidelity contract
| Surface | Composition and behavior |
| --- | --- |
| Shell | Default navy canvas, teal selected destination and muted blue inactive destination; the shared Appearance selector changes color roles while retaining scene state; 44px primary controls. Dynamic viewport height and safe-area padding keep navigation clear of device edges. |
| Corridor, portrait | Compact stage and lane selectors above a dedicated scene area; camera controls, optional Turn/Tilt controls and the horizontal step rail follow in normal scrolling flow. The controls stay clear of the canvas and record cards, including short portrait screens. All source lanes remain reachable through the selector and previous/next controls. |
| Corridor, landscape | A 236px information and step rail beside the scene, reduced to 210px on narrower landscape screens. Step cards scroll independently. |
| Corridor geometry | Reuse the desktop `CorridorScene`; compress the longitudinal lane axis while preserving upright placard proportions. Clip at the outer canvas, keeping preserve-3D carriers free of grouping properties. |
| Corridor records | A native dialog mounted at the document body presents the selected record with its existing card color, complete facts, nested records and previous/next navigation. Its lazy content sizes intrinsically within viewport bounds, so both the opening status and loaded record remain visible; long content scrolls inside the dialog. Linked references open the exact source, instruction, artifact, comparison or decision in a readable companion; Back restores the originating record. Close, Escape and backdrop return to the corridor. |
| Corridor overview | The same renderer fits multiple colored lanes into the canvas. A compact toolbar switches between One lane and Overview; a grouped Explore dialog owns stage, lane visibility, kind, search and arrow controls. Empty filters leave a clear reset action. Overview supports up to 6× its fitted scale through buttons, wheel and pinch, allowing close inspection of individual placards. Its pan reach grows with zoom so outer lanes remain reachable; One lane retains its 2.5× limit. Mode changes preserve their existing reset or filter-adjustment behavior. |
| Corridor camera | Move/orbit gestures, pinch, keyboard and tap controls retain direct tracking. Top, Isometric and Side use a short, cancellable spring with continuous yaw. Side uses slightly higher damping for about 12% less rebound; Top and Isometric retain their original motion. Reset uses a quicker spring with a small bounce, returning pitch, yaw, pan and zoom together to the receiving layout’s original framing while restoring its existing non-camera defaults. A new preset takes over from the current pose; direct manipulation cancels the spring immediately. Reduced motion selects the destination directly. Pitch spans 0–100° so most of its travel shows the useful top surface. The scene tracks direct input without a competing CSS transition; flags and their poles share one upright plane. Travel remains available. Travel suspends while a companion, another view, a hidden document or reduced-motion preference makes animation ineligible. |
| Plate | Eight rows and twelve columns of touch-sized wells, raised rims and luminous result colors. Each well keeps at least a 44×46px target. Portrait scrolls the board horizontally; wider landscape reveals its full width. Page width stays within the viewport. |
| Plate history | Well board / 3D plate share one well, result, lens and pin selection. Sample history preserves the wind-up, spring entrance, clamps, extrusion and gossamer thread, then allows direct camera exploration. The compact badge reads Timeline view. Touch controls carry the return action; Esc and U key hints appear only in the desktop presentation. By result / Over time sets chronological spacing; Compact / Spacious sets visual depth. Selecting either layout control from Plate overview opens Sample history through the same entrance, preserving the selected well and result; using the currently selected value also reveals its layout. Fit plate, Center sample, zoom and Angle controls provide direct alternatives to orbit, pinch and pan. Overlays follow the current camera, which survives section return; changed bounds or depth refit the plate. Plate overview returns to its prior camera. |
| History source | A compact navy rail uses teal for the shown history identifier and muted blue for source context. Stored/example, loading, missing, empty and unavailable states are explicit; Retry stays in the rail. Successful histories replace the corresponding example wells throughout the retained projection, including empty/missing histories. A previously read desktop hover uses that cached history and names its source without fetching again. |
| Color meaning | Status, reason, storage, and query lenses use shared `stackLens` paints and a persistent compact legend on desktop and mobile. Both the overview wells and history discs follow the selected lens. Hatching and warning rings retain their source meaning; text labels accompany the color. |
| Details | The mobile record presents Why, Files, Lifecycle and Sample as touch-sized section controls. It reuses desktop charts, metrics, comparisons, replacement links, sample details, file copy/restore and Athena actions. The shared Plate command owner resolves current result metadata, validates the action and rechecks consent, environment, role and resource clearance before effects. Copying a permitted location remains available in read-only environments. A compact data-posture disclosure and full story/policy index preserve overview context. |
| Deferred views | A short, announced opening status occupies the receiving panel. A failed module shows a reload action in the same navy/teal palette. Mobile navigation remains available; reload starts the showcase at its default state. |
Portrait and landscape are both functional. Rotation offers more space rather than an entry requirement. Browser zoom remains available outside the corridor and flat plate direct-manipulation canvases. Plate gestures belong to the scene; records and controls outside it retain ordinary page scrolling. Reduced-motion preferences remove camera transitions and smooth scrolling. Primary controls and card alternatives remain usable with keyboard focus.
## Source ownership
- `src/app/components/mobile/MobileShowcase.tsx` owns the two destinations, first-visit Plate loading, retained mobile views, and compact About dialog. `mobile-showcase.css` owns their layout.
- `MobileCorridor.tsx` and `mobile-corridor.css` own the touch projection, lane selection, camera controls, step rail and record dialog. `corridorView.ts` composes the lane, stage, kind and query filters before rendering. `MobileCorridorExplorer.tsx` and `MobileCorridorDetails.tsx` load when requested. `MobileReferenceRecord.tsx` is a separate lazy exact-ID receiver using `services/recordNavigation.ts`; it presents the selected record without loading desktop chapter code. `components/corridor/CorridorScene.tsx` owns the renderer and card palette shared with `views/LanesView.tsx`; `corridorCamera.ts` owns shared pitch bounds, continuous yaw and the three preset destinations. `useCorridorPresetMotion.ts` owns preset and Reset motion, replacement, direct-input cancellation and reduced-motion behavior; the renderer keeps direct input free of CSS transitions. Its pure `corridorProjection.ts` boundary resolves relationships from the supplied visible cards and lanes, so every painted arrow has two visible endpoints. The renderer receives canonical data through its callers.
- `MobilePlate.tsx` and `mobile-plate.css` own the board/3D choice, touch controls, story index and record companion. Its lazy `PlateHistoryProvider` and `PlateOverlayProvider` consume session-owned history and recovery state; environment and notifications live above the responsive workspace. Accepted actions survive both scene navigation and desktop/mobile replacement. `PlateScene3D` receives an explicit compact presentation and active flag. `PlateCameraControls` owns the shared fit, center, zoom and angle rail; `useProjectedCamera` keeps labels and the record thread aligned with manual exploration. `PlateLensLegend` projects the same paint vocabulary as the wells and discs. `ResultTray.tsx` shares record columns and write actions between presentations. `plateProjection.ts` supplies accepted file/query facts and posture summaries to both; `usePlateTouch.ts` reuses the two-contact gesture controller. `data/wellResults.ts`, `plate/stackLens.ts`, `plate/plateGeometry.ts`, and `services/dataAvailability.ts` retain data, color, geometry and policy meaning.
- `services/plateHistory` owns selected-well GraphQL reads, complete canonical decoding, fixed-clock agreement, request cancellation and successful-read cache lifetime. `plate/PlateHistorySource.tsx` and `plate-history.css` own the shared compact source rail. The successful-read Map is a lazy browser-session resource; in-flight cancellation remains with the requesting view. Accepted file overlays apply after fetched histories. Missing and empty successful reads remain distinct from an unavailable source with explicit example fallback.
- `main.tsx` installs one typed `ThemeProvider` above both workspaces. Its Appearance choice persists independently of scene and accepted-record state. `App.tsx` and `useCompactViewport.ts` select the receiving workspace. `DesktopWorkspace.tsx` contains the original desktop shell and providers behind a dynamic import. `components/DeferredView.tsx` owns loading and download-failure recovery. `index.html` allows safe-area layout without limiting user zoom.
- `services/exploration/ExplorationProvider.tsx` owns shared view intent above `App.tsx`'s responsive branch: scene, desktop Corridor controls, Plate options, selected well/result and compact Board/3D choice. Navigation, Corridor and Plate have separate context subscriptions. This retains the explored view while each workspace remains independently loadable; companion scroll and camera fitting retain their existing scene owners.
- `App.tsx` installs shared Environment and Notification providers plus `services/browserSessionContext.tsx` above responsive projection. `browserSession.ts` retains feature-factory values per app instance; immutable state cells expose stable subscription/snapshot methods. Deferred Record, Comparison and Plate providers keep their reducers and commands in their feature modules. Athena repair state records its completion deadline and notice context: a receiving Plate schedules only the remaining delay, and an overdue repair completes once on return. Timer cleanup stays local; rebuilds remain queued.
- `components/useLanesShortcuts.ts` maps desktop **C → Corridor** and **P → Plate** through that same navigation owner. The active, visible Lanes workspace owns the listener; a retained Lanes view releases it during an exact-record visit to another section. Input, textarea, select and editable content retain typing; modifiers, composition, repeated and already-handled key events retain their existing behavior. Compact touch navigation stays unchanged. The scene buttons carry small key hints and `aria-keyshortcuts`; Plate's existing U and Escape controls keep their separate history behavior.
## Corridor capability parity
The single-lane mobile entry remains the default. The additional controls replace the earlier single-lane-only scope; desktop composition remains unchanged.
| Desktop operation | Mobile receiver |
| --- | --- |
| Multi-lane and stage view | Overview, stage buttons and the Explore scope selector. |
| Hide, reveal and focus lanes | Explore → Lanes; Focus reveals and selects the named lane. The lane selector and previous/next rail remain direct paths. |
| Card-kind and text filtering, arrows | Explore → Search and Layers; one visible population feeds cards and cross-lane edges. |
| Flags, surface labels, connections and streams | Shared scene geometry plus Lane details and the Streams disclosure. |
| Drafting key and nested cards | Explore → Layers and drafting key; card companion retains nested labels and identities. |
| Travel and camera | Persistent camera controls, continuous yaw, top-weighted pitch and three spring presets. Scene gestures own only the canvas; record companions scroll normally. |
| Exact referenced records and return | Linked record buttons open source-owned readable fields and a Back action within the companion. Missing records show a bounded unavailable state. |
## Evidence-informed boundaries
The [WCAG target-size guidance](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) sets a 24px minimum with conditions; this composition uses larger primary targets and readable alternatives for small scene objects. The [dragging-movements guidance](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html) supports separate tap controls for camera adjustments and direct record access. The [orientation guidance](https://www.w3.org/WAI/WCAG22/Understanding/orientation.html) supports functional portrait and landscape views.
Native buttons, selectors, dialogs, and [disclosures](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) carry state and keyboard behavior. [Touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/touch-action) is scoped to the corridor canvas so its pointer gestures coexist with native scrolling elsewhere. These references guide implementation; browser and device observations establish actual behavior.
## Focused verification route
Use a production build for the final browser pass. Check the initial corridor with camera controls and the step rail in separate portrait flow, then open each companion at 390×844 and 844×390. Hold the lazy record download to check the opening status, then release it and verify painted record content and focus return. In Overview, reach the shared 6× limit through buttons, wheel and pinch, pan by touch, then return to the original single-lane framing. Continue with combined stage/kind/search filtering, lane hide/focus/reveal, step detail open/advance/close, exact reference return, camera adjustment/reset and travel suspension. Select Top, Isometric and Side to check their spring settle, then interrupt a preset or Reset with direct input. Reset an angled, panned and zoomed camera to confirm a complete return, its existing filter/travel behavior and the small rebound. Mobile lane selection still recenters directly. Reduced motion reaches the destination immediately. Drag through the yaw seam and pitch horizon, and confirm each flag remains attached to its pole; the corridor carries no U/V/Z drafting legend. Then check Plate selection, all four lenses, Board/3D switching, Sample history entrance/release, result/time spacing and compact/spacious depth, result navigation, sample and file controls, and return to the well. Restore a shared C3 BAM and confirm both aliases update. Repair A9 T1 while retaining the queued behavior of its older rebuild. Inspect E3 consent holds. Verify a stored title with opaque result IDs, source status, complete history and file aliases. Exercise failed-read Retry, a rapid well change, empty/missing history, and return from Corridor; stale responses must not replace the selected well. The durable mobile browser journeys check retained selections and explored cameras, shared restore actions, successive orbit/pinch movements, the next control tap, fitted history bounds and immediate reduced-motion fitting. Compact geometry and projection tests cover framing and consent precedence. Check keyboard focus, reduced motion, and a complete long history.
For startup changes, run `npm run test:startup` after `npm run build`. The generated manifest guards deferred workspace boundaries, a 450 kB uncompressed initial-JavaScript budget, and emitted asset completeness. With the browser cache disabled, confirm desktop and Plate chunks are absent from the first mobile request set, Plate loads only on first selection, and a failed download leaves Corridor reachable with a working reload recovery. Compare the same production server and viewport before and after; distinguish actual transferred bytes from Vite's gzip estimate. The static server currently sends uncompressed assets; upstream hosting compression remains a deployment observation.
For accepted-state handoff, hold a specimen, resolve a comparison and choose a read-only environment before crossing to mobile and back. Confirm the accepted states and refusal context remain, then reload to confirm a fresh example session. Restore C3 BAM and verify both aliases in both layouts with one cached history read; interrupt an A9 repair by delaying the receiving Plate module beyond its deadline and confirm one completed result and notice.
For responsive handoff, select desktop Plate overview, resize to 390px and back to 1512px, then repeat with C3 R2, a different lens and Over time / Spacious history. Start separately on mobile to confirm Well board remains selected after a desktop round trip, and confirm explicitly choosing Corridor remains effective. These journeys assert the displayed record and scene, rather than only the navigation label.
Representative dimensions are 360×640 and 390×844 portrait, 667×375 and 844×390 landscape, 768×1024 tablet, and the 1023/1024 desktop boundary. Inspect the desktop corridor at a laptop width after the mobile checks. Confirm page width equals viewport width; horizontal overflow belongs only to the intended board or card rail. Exercise the Appearance selector in portrait and landscape, checking both scene and companion legibility and retained well, camera and edit state. Keep cycle screenshots in ignored `.visual-runs/`.
The browser pass establishes responsive rendering and pointer/keyboard operation in the available Chromium browser. Unit tests cover pointer transitions and cancellation separately. Physical iOS/Android touch behavior and hosted publication remain checks for the receiving device and host. Production serving and startup tests retain the ordinary Node boundary.
## `docs/operational-workflows.md`
Source document: `docs/operational-workflows.md`.
# Map workflows and quality reviews
Map and Quality Control retain accepted actions for the current browser session. Section navigation and desktop/mobile layout changes preserve that state; reloading restores the example baseline. Each command resolves its own record and rechecks the current permission scenario before accepting a change.
## Map
The relationship graph contains systems and workflow examples. Selecting a node exposes its available sample, order or review actions through the same legal transitions used by specimen records. Held orders can resume or cancel; reviews can request changes and resubmit; fulfilled and cancelled orders stay terminal. The work-area label describes the node's context.
`mapOperations.ts` owns accepted node state and action selection. Its session resource initializes on first use. Permissions use the node's canonical classification and the corresponding `sample.manage` or `review.approve` capability. The graph's system nodes have no canonical patient/resource geography; their local workflow examples remain separate from specimen records and clinical release.
## Quality Control
Each quality gate has a measured outcome and a separate recorded response. Visitors can acknowledge a passing gate, retain a warning/failure hold, or request a rerun. **Reopen review** restores the response choices. The recorded response updates the gate card and review count immediately.
`qcReviews.ts` owns those responses. Wet-lab gates require `sample.manage`; sequencing and secondary analysis require `analysis.run`; sign-out requires `release.manage`. A response leaves the measured metrics, gate status and blocking flag intact. A rerun request records intent in this browser session; executing laboratory work or releasing a run would require a separately authorized backend workflow.
## Evidence and recovery
`tests/map-operations.test.mjs` observes legal branching, exact-node updates, terminal states and stale-authority refusal. `tests/qc-reviews.test.mjs` observes exact-gate responses, reopen recovery and preserved measured failures. Both exercise the actual permission policy, including role/environment changes after an affordance was shown.
The matching browser specifications exercise visible outcomes, section-navigation retention and a later Viewer refusal in production Chromium. Existing available-action and workspace-scroll checks cover surrounding controls and reachability. Map and QC retain their existing layout, palette and graph/card composition. A denied action explains the current permission requirement while retaining the accepted state.
## `docs/permission-scenarios.md`
Source document: `docs/permission-scenarios.md`.
# Permission scenarios, scoped reads and accepted commands
Profile lets a visitor choose a synthetic persona, workspace role and audience perspective. Choices apply immediately. The scenario, accepted records, file recovery and refusal notices belong to the application session and survive desktop/mobile layout changes. Reload starts a fresh example session.
This is a public portfolio scenario. Its finite actor and role selectors demonstrate permission behavior; verified identity and private data require the separately planned server identity boundary. Public workflow examples in the other desktop sections remain demonstration context. The Corridor receiver and Plate records, GraphQL reads, Access Grid and accepted commands use the boundaries below.
## Policy ownership
`shared/permission-scope.mjs` owns explicit job capabilities, scenario validation, grant replay, canonical record ownership and field projections. The browser and server receive the same catalog from `services/accessService.ts` through `permissionScope.ts`. Feature records remain deferred. The API creates one immutable scope per request alongside its request-owned data repository.
Lab Operator manages samples and orders; Clinical Reviewer reviews results; Analyst runs analysis and recovery. Viewer and Auditor can read permitted records and file locations. Release Lead combines working capabilities. Administrator adds policy configuration. Selecting another role retains the persona's environment assignments and clearance. Selecting another persona restores its baseline role and audience. Audience perspective changes presentation independently of authority.
A decision checks supported input, consent, environment write settings, membership, canonical resource sensitivity and the requested capability. A record command additionally requires a sufficient resource/geography grant. Validation and Production retain their read-only setting. Reading skips the write-setting requirement while retaining the other boundaries.
## Access Grid
The acting scenario authorizes Save grants. The inspected person identifies whose matrix will change; inspecting an Administrator does not give the acting visitor that role. Effective scope uses the acting role for the active persona and the inspected person's baseline role for other people. Resource-specific task capabilities remain a separate requirement from a read/write grant.
The session owner accepts a complete known matrix synchronously, validates every cell and rechecks the current actor and environment. Each changed cell becomes a bounded grant command carrying its actor, target, resource, geography and level. The server replays the same validated commands against canonical seeds rather than accepting a claimed capability set or effective matrix. The log accepts up to 64 saved cell-change entries, including repeated changes to one cell. A save that changes no cells adds no entries. An over-limit save preserves the accepted scope and open draft, and names **Reset scenario grants** as recovery. Unsupported inputs also preserve the accepted scope.
**Reset scenario grants** restores every person’s canonical example grants, clears the accepted command log and replaces the open Access Grid draft with those restored values. It retains the acting persona, role, environment and audience, the inspected person and effective-scope display choice, and unrelated accepted records, file recovery and exploration. The accepted owner updates synchronously so the grid reads the restored matrix immediately.
This local recovery is available in Viewer and read-only scenarios whenever saved grant changes or an open draft exist. It restarts the public experiment; **Save grants** continues to require the current policy-edit capability and a writable environment. This replaces reload-only recovery for grant experiments. Reload still starts a fresh application session. Verified identity and durable policy administration retain separate owners.
The scope key includes the normalized persona, role, environment and accepted grant commands. Two different grant sets cannot collide merely because they have the same edit count. Server cursors use a bounded digest of this key. The digest namespaces paging; it grants no authority.
## Read projection
The generic Corridor is public workflow context with no patient ownership on its cards. Its receiver checks the scenario's read capability and environment membership. Plate has a stricter record projection:
- A well requires plate-map scope at its canonical geography; a result also requires run-metadata scope and its permitted anchor well.
- Known specimens supply geography, classification and consent. Legacy stored rows use this same canonical ownership. Unlinked generated examples use the declared collection geography. Unknown specimen ownership receives a bounded refusal rather than an actor-region guess.
- Coordinates, sequence, kind, state, date and short navigation labels form the minimum de-identified timeline. Clinical titles, reasons, findings, triggers and related narrative require the classification ceiling and variant scope. Withheld detail receives a neutral description.
- Patient linkage, quality measurements, contamination and laboratory fields follow their own resource grants and classification ceiling. Field omission represents an unavailable field, never a zero measurement.
- A restricted file projection carries its scope provenance. Readiness describes withheld information as outside scope; an absent visible file does not establish that no file was produced. Permitted file rows and their known availability remain inspectable.
- Reviewer, Auditor, Release Lead and Administrator may inspect a bounded consent-hold explanation. Analysis and file operations still obey the hold. A newer canonical hold takes precedence over an older active stored alias.
- Lists filter before counts, page cursors and relationship links. Direct IDs, superseded results and reused-file references use the same receiving policy.
Default grants preserve C3 file recovery. A9's protected details and repair require Dr. A. Okafor and Staging; choose the Analyst role for its partition-repair example. The default scope retains its minimal timeline. Clinical approval also remains PHI-class: the default Platform Lead's limited clearance cannot approve it by changing role alone. Choose Dr. A. Okafor, Clinical Reviewer and Staging to explore approval.
## History and responsive recovery
The Plate cache partitions reads by the complete permission scope and collection/well identity. Switching scope changes the rendered projection immediately, cancels the former request and checks the captured scope again before a response can publish. A late response cannot fill the current scope's cache. Returning to a previously permitted scope may reuse its own successful read. Resetting grants derives the seed scope key for the current selection, so this same reconciliation restores its permitted projection and may reuse its existing cache partition. Reset leaves history caches and accepted file-recovery owners intact.
The source strip distinguishes permitted history, denied access, missing records, empty histories and retryable unavailability. Denied access and unknown or conflicting stored ownership suppress both earlier cached records and examples. Ownership uncertainty offers Retry and remains suppressed until a confirmed successful read. Missing or empty successful reads replace earlier example history. A transport failure may retain only the examples allowed by the current scope, with an explicit unavailable source. Selected details, hover cards, story links and counts receive the same projection; permission changes leave accepted edits and the visitor's underlying exploration selection with their existing owners.
## Accepted commands
Callers submit identifiers and intent. `recordCommands.ts` resolves the current specimen or biomarker owner, checks its canonical consent and geography, evaluates the action/resource contract and asks `recordSession.ts` for the legal transition. Operational sample/order management uses the wet-lab or accessioning resource clearance; clinical approval uses the stricter clinical-report resource. These public workflow commands retain that boundary independently of access to protected Plate findings and files. Unknown records, missing ownership and repeated transitions return tagged refusals.
| Workflow | Capability | Canonical resource |
| --- | --- | --- |
| Sample progression | Manage samples | Wet-lab process |
| Order place, start, hold, release, fulfill or cancel | Manage samples | Accessioning |
| Specimen and biomarker review, approval or sign-off | Review clinical results | Clinical report |
`plateCommands.ts` receives the collection plate, anchor well and result ID, plus an action and file kind or restore-tier ID. The collection plate may differ from the physical run plate. Current permitted stored history takes precedence over bundled examples. File restore requires analysis capability and a write grant for the file's resource; partition repair uses variant-call write scope; file-location copy uses read scope. Every Plate command also checks canonical record classification, so readable timeline metadata alone permits no operation on protected files. The command owner resolves the current record and owner again before effects.
Accepted file restores retain their physical object identity while each receiving result keeps its consent. Accepted query repairs keep their completion deadline across layouts. A later permission change governs new commands; previously accepted work completes, with record-specific notifications shown only in a still-permitted scope. These remain local showcase actions. Plate histories keep their indexed, parameterized read-only path; the separate disposable Source workspace uses its own transaction owner; SQL views cannot identify a browser persona through one hosted application account.
## Evidence and continuation
Focused policy/API cases compare direct and nested reads, field omission, canonical holds, malformed grant replay, filtered counts and cursor boundaries. Client cases cover acting versus inspected authority, scope downgrades, late-response cancellation, denial without example fallback and responsive return to a permitted cache. The grant-recovery cases exercise seed restoration, the saved-entry boundary and retention of independent accepted work. Command and browser regressions retain the working recovery and clinical-review paths.
These checks target consistent finite-scenario behavior. [Disposable Source workspaces](#document-docs-visitor-workspaces-md-49294a63218a) use server-issued origin-bound cookies and current simulated policy at their command boundary. Saved metadata has bounded history and expiry. Verified identity remains a separate design and acceptance boundary for private records or real multi-user work. The ordinary Node server and PostgreSQL clone retain their stored-history boundary.
## `docs/persistent-data.md`
Source document: `docs/persistent-data.md`.
# Stored Plate records
The public edition persists synthetic Plate history through PostgreSQL and serves the same canonical records through GraphQL. Use the [isolated clone](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) for a complete setup, or [PostgreSQL configuration](#document-docs-postgresql-md-a7cc27814ec8) for an existing owned database. Bundled examples remain available when database settings are absent. The retained MySQL adapter is an optional compatibility implementation behind the same repository boundary.
## Record ownership
The catalog owns a version and fixed observation date. Wells have plate-local coordinates. Results have opaque global IDs, a well anchor and an ordered sequence. Physical files have one object-key identity; each result owns its artifact reference, legal hold, reuse lineage and initial restore state. Relational columns, foreign keys and indexes carry those relationships. Bounded JSON carries leaf details such as metrics.
[Canonical seed preparation](#source-d95e72141ac1) validates the supplied synthetic catalog before either SQL adapter installs it. PostgreSQL owns [its schema](#source-a3de6288e2bd), immutable checksum, transaction and physical-shape signature. MySQL retains its separate [schema](#source-3f3e33235e4a) and ownership marker. An installed catalog remains authoritative when a later bundled seed differs; changing a fixture performs no automatic data replacement.
[Shared record decoding](#source-7fabf26ac827) returns fresh canonical values and checks text, supported Unicode, enums, dates, null meaning, numbers and file identity. The server validates before publishing a stored read. The browser validates a complete history before replacing its selected record projection. Successful empty history stays empty, and a missing well stays missing.
## Read and connection ownership
One GraphQL operation owns one lazy, short-lived connection and read-only snapshot. Corridor-only requests open no database connection. Query parameters remain bound values. Histories retrieve artifacts in a batch and cache results inside that request, preserving a consistent operation without querying each artifact separately. Cleanup owns transaction completion and transport release; cancellation settles the underlying driver work. [PostgreSQL](#document-docs-postgresql-md-a7cc27814ec8) describes isolation, bounded retries and ordinary-role privileges.
A configured outage, missing schema or invalid stored record retains the stored-data failure. The browser can show explicit Retry or example-history controls without silently replacing accepted storage. Source metadata has its separately scoped write contract in [visitor workspaces](#document-docs-visitor-workspaces-md-49294a63218a); ordinary Plate catalog reads do not mutate results or files.
## Browser receiving scope
The selected well's history is the first stored receiver on desktop and mobile. Its source strip identifies stored records, examples, loading or recovery. Successful histories are cached by current permission scope; failed reads remain retryable. Corridor and overview projections retain their bundled owners, so the source label names selected history rather than claiming whole-application durability.
Physical-file recovery overlays remain browser-session actions. Reload begins a new example session for those actions. Opaque result IDs carry no navigation encoding. The catalog observation date must agree with the showcase lifecycle clock before the client accepts stored history.
## Setup, recovery and evidence
Use [local operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) for initial setup, app/database restart, trusted backup restore and confirmed project reset. Ordinary build/start performs no DDL. Repeated explicit initialization validates owned schema and retains accepted records; drift, foreign tables or incomplete ownership receive a recovery error for inspection. Application rollback preserves database contents.
The ordinary suite checks example reads, DTO agreement, invalid/empty/missing states, request disposal and production serving. [PostgreSQL proof populations](#document-docs-postgresql-md-a7cc27814ec8) exercise actual initialization, constraints, relationships, snapshots, rollback and runtime-role HTTP behavior against independently owned disposable databases. The container proof adds app/database restart, original-workspace backup recovery and two-clone isolation. A new host still needs its own receiving observation.
Maintainers changing the retained MySQL adapter can select `npm run test:mysql` with a fresh build, MySQL CLI and a disposable loopback database named `sot_*_test` or `sot_*_proof`. [The proof runner](#source-a65b7b4c6772) owns opt-ins, destructive ordering and final initialization; it preserves catalog import, store and HTTP coverage without adding a public hosting path. Keep shared or remote production databases outside these checks.
Future result writes, private identities and external assay retrieval need their own authorization, mutation, audit and operational contracts. Current file records describe locations and checksums; they do not upload assay binaries.
[Server](#source-93e4a5263a59) · [Documentation](#document-docs-readme-md-0b5ca119d2be)
## `docs/plate-workspace.md`
Source document: `docs/plate-workspace.md`.
# Plate workspace at compact desktop widths
The Plate scene retains room for the selected sample and its result record at 1024px. Its scene-preserving layout sits alongside the other [bounded record workspaces](#document-docs-workspace-layout-md-b161445e3297).
## Composition and ownership
`LanesView.tsx` holds the local disclosure selection; `PlateWorkspace.tsx` renders the two reading rails and owns their entry/return focus. At desktop widths from 1024 through 1359px, **Sample histories** and **Sample details** remain visible above the scene. Each opens its existing rail over the scene and focuses its close button for immediate keyboard entry; opening one closes the other. Choosing a story returns focus to its trigger and reveals the selected result. A rail's close button or Escape closes that rail and restores trigger focus. Escape elsewhere retains the Plate's existing release behavior.
From 1360px, both rails sit beside the scene as before. Below 1024px, the existing mobile Plate composition takes over. The compact disclosure does not change the scene's dimensions or refit its camera when it opens. Its scrollable contents stay mounted while closed. Visual order and DOM order remain histories, scene, sample details.
This arrangement keeps the three-column result tray instead of introducing a second desktop record renderer. Persistent compact rails left too little room for those columns; a separate modal would interrupt the sample/result relationship. Local overlays leave the current well, result, pin state, request/source feedback and retry path owned by the existing exploration and history services. The toolbar identifies the selected well even when its details are closed. The result header can wrap its metadata while its close and pin controls remain inside the tray.
`plate.css` owns the desktop rail geometry and uses existing shell tokens. The Plate camera, scene motion, lenses, history spacing, depth, result commands and mobile layouts retain their existing owners. The empty sample rail now invites selecting a well instead of displaying the Corridor drafting key.
## Receiving evidence
`tests/browser/plate-workspace.spec.mjs` checks the 1024px scene width, rail exclusivity, visible selection and source state, keyboard close/return, unchanged scene width during disclosure, one read for the selected history, the bounded record close control, and retained R2 selection across 1512px and the 1023px mobile boundary. Existing Plate layout and history-feedback checks cover spacing/depth, pinned selection, loading feedback, late-response isolation and cached reads. Settled before/after captures cover 1024×768 and 1512×982, with a mobile-boundary capture at 1023×768.
These observations establish the Plate layout and its retained operations. They leave the other workspace families and live hosted-database behavior to their own receiving checks.
## `docs/postgresql.md`
Source document: `docs/postgresql.md`.
# PostgreSQL catalog and visitor workspaces
The application supports PostgreSQL 18 with `pg` 8.23.1. It persists the canonical Plate catalog/history and expiring Source metadata workspaces through the existing GraphQL APIs. Other workflow edits retain their browser-session lifetime. The public edition supports PostgreSQL and bundled examples. The retained MySQL adapter remains an optional compatibility implementation.
## Configure and initialize an owned database
Use a database created for this application. Keep configuration in an ignored `.env` file or server secrets. Supply `DATABASE_PROVIDER=postgres`, `PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER` and `PGPASSWORD`. The default TLS mode is `verify-full`, with certificate verification; `PGSSLROOTCERT` may identify a trusted CA file. Use `PGSSLMODE=disable` only for an explicitly controlled local/Compose network. Credentials remain server-only. The configuration owner rejects mixed MySQL/PostgreSQL settings and incomplete selections.
Build with `npm run build`. With an ordinary database-owning setup role selected, run:
```sh
npm run database:init
node --env-file-if-exists=.env scripts/database.mjs workspace-init
```
Each command owns one transaction, a bounded application advisory lock, its immutable schema checksum and its completion marker. Catalog seed revision/digest are separate from schema identity. First setup creates and seeds the owned relations atomically. Repeated setup validates the installed shape and retains accepted records. Ordinary app startup opens existing records; explicit setup owns DDL.
After setup, select a separate runtime login. Grant it `USAGE` on `public`, `SELECT` on the catalog's six `showcase_*` relations, `SELECT` and `UPDATE (singleton)` on `showcase_workspace_schema`, and `SELECT, INSERT, UPDATE, DELETE` on `showcase_visitor_workspaces`, `showcase_workspace_sources` and `showcase_workspace_receipts`. The marker update privilege permits the admission lock. Keep schema creation/alteration with the setup owner. The [clone initializer](#source-cba6d2e7ece6) automates these exact grants; a managed host supplies its own administrative route.
Run the Node server with the selected runtime settings:
```sh
node --env-file-if-exists=.env scripts/serve.mjs
```
The [local clone runbook](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) supplies the complete container recipe, clone identity and backup/restore route. It uses these same native migration and seed owners.
## Record and transaction contracts
Opaque identifiers use case-sensitive `C` collation. Composite foreign keys preserve Plate/well ownership, earlier supersession and reused-file identity. Identity, order, revisions and expiry occupy relational columns. Bounded `jsonb` contains leaf metadata; shared decoders retain domain dates, null meaning, safe integers and supported Unicode.
Source inputs containing NUL or an unpaired surrogate receive `INVALID` before SQL, preserving the editor draft. Logical limits measure the shared compact UTF-8 JSON representation. SQL imposes a separate defensive ceiling on PostgreSQL's rendered JSON text; internal `jsonb` storage bytes do not define command admission or identity. Exact retry fingerprints use the normalized command serializer, independent of JSON key order in storage.
Catalog reads use one request-owned repeatable-read snapshot and batched artifact retrieval. Workspace reads use repeatable read; writes use read committed with workspace locks so waiting commands see the preceding accepted receipt/revision. Admission locks serialize quota checks. Short-lived clients own acquisition, query, rollback/commit and transport cleanup within a finite deadline. Serialization failures and deadlocks receive at most one whole-transaction retry within that deadline. An uncertain commit returns to the original idempotency key; its receipt resolves the accepted result.
The same permission scope, approved GraphQL operations, masked errors, cookie authority and request admission govern each adapter. A configured unavailable store reports its actual state. Database selection never silently replaces accepted stored data with example data.
## Recovery and changes
A fresh setup failure rolls back its DDL, rows and completion marker. Correct the cause and retry the explicit initializer. Partial unmarked tables, newer schema versions, checksum differences and changed columns/constraints/indexes/triggers/RLS stop setup with a recovery error. Keep the existing database and inspect its owner and version before choosing a repair. Apply future changes through a versioned forward migration; preserve released schema checksums.
A complete catalog remains authoritative when a later supplied example seed differs. Changing examples alone performs no live-data replacement. Create a separately owned disposable database to inspect a new seed; a reviewed migration governs changes to an existing one.
A workspace lasts 24 hours and also requires its original cookie verifier and exact origin, including port. Preserving database rows alone grants no new browser access. The clone backup/restore proof uses a controlled origin within that lifetime, and its reset targets only the explicitly confirmed clone.
## Focused evidence
Build first. On an invocation-owned loopback database whose name matches `sot_*_test` or `sot_*_proof`, select `POSTGRES_TEST=1` and run the SQL populations separately:
```sh
node --env-file=.env --test tests/postgres-catalog.mjs
node --env-file=.env --test tests/postgres-workspaces.mjs
node --env-file=.env --test tests/postgres-http.mjs
```
These opt-in checks create and remove their named test relations. Use isolated proof databases, ordinary setup credentials and separate `PGRUNTIMEUSER`/`PGRUNTIMEPASSWORD` where the fixture supports them. Keep hosted/shared databases outside this route.
PostgreSQL 18.6 observations cover atomic and competing initialization, ordinary-role constraints, retained records, bounded/batched relationships, consistent snapshots, schema drift, exact retries, concurrent stale writes, quotas, expiry and reset isolation. Query-plan observations record returned rows/loops on the synthetic fixture; a tiny dataset can reasonably use a sequential scan. HTTP and restart checks distinguish actual process recovery from creating another client. The PostgreSQL 18.7 container recipe also has a separate app/database restart and backup/restore observation.
The Node driver remains outside browser bundles. Existing example/MySQL contracts, production build and startup budget remain receiving checks for source changes.
[Driver transaction ownership](https://node-postgres.com/features/transactions), [client deadlines](https://node-postgres.com/apis/client), [verified TLS configuration](https://node-postgres.com/features/ssl), and [PostgreSQL isolation](https://www.postgresql.org/docs/18/transaction-iso.html) ground these choices.
[Database choices](#document-docs-database-choices-md-a44edbfece29) · [Server](#source-93e4a5263a59) · [Documentation](#document-docs-readme-md-0b5ca119d2be)
## `docs/presentation-styles.md`
Source document: `docs/presentation-styles.md`.
# Presentation visual fidelity contract
The presentation library preserves each brief's visual identity while visitors choose how to read its content. **Deck styles** uses each curated brief's declared style. **Briefing**, **Evidence review** and **Report** provide distinct pacing and structure over the same source sections. [The research decision](#document-docs-research-presentation-formats-md-bf93b4ff14d5) records the evidence, alternatives and transfer limits.
## Identity and selection
The six styles retain their existing colors, typography, cover art and curated content. **Editorial Brief** names the color-block style without implying confidence in a scientific finding; it supersedes the former display name while retaining its stable internal key. **Spectrum** names the violet field, luminous accents and technical typography. Selecting a named style applies an explicit common override to every cover and the artifact composer; returning to **Deck styles** restores the original identities. Artifact composition starts in Blueprint.
Opening a brief resolves one concrete style and source identity. Back to library or Escape retains style, format and selected artifacts. Opening another brief starts at its first section. Within a brief, changing format retains the source section so the visitor can compare views without losing their place.
## Format composition
| Format | Reading structure | Navigation and visual rhythm |
| --- | --- | --- |
| Briefing | A prominent source headline and supporting evidence share a two-column page. Measures keep their labels, units and qualifiers; explanatory prose remains available. | Previous/Next and a section counter replace the page. A short 180ms arrival makes the change legible. The local viewport scrolls when content exceeds the available height. |
| Evidence review | The established oversized titles, angled stamps, color fields, grids and expressive cards remain the visual vocabulary. The angled cover stamp has its own header slot; title type scales with the available document width. Pages grow to fit their content. | A persistent chapter rail identifies the source sequence. Selecting a chapter scrolls to it; an arriving page reveals its content with the existing gentle upward movement. |
| Report | Continuous sections use 28px headings, 15–16px prose, approximately 1.6 line spacing and a maximum reading column near 78ch. The deck identity remains above the document. | A contents rail carries section labels and their full headings. Previous/Next also moves between sections. Values and explanations stay together in reading order. |
The toolbar and bottom navigation remain in place while the content viewport scrolls. Contents and chapters have their own scroll area when needed. At compact laptop widths the rail narrows and content padding decreases; long prose continues vertically instead of being clipped. Reduced motion presents content immediately and uses immediate section navigation.
## Appearance boundaries
The application appearance controls the surrounding workspace, format controls and selected style's text/surface pair. A style's accent remains a swatch and border in the library. Under Dark and Light, deck paint retains its own identity. High contrast maps document foregrounds, surfaces, rules and accents to shared semantic tokens; it preserves source content and layout. The implementation uses local paint roles rather than color inversion or filters.
## Content and state ownership
- `views/PresentationsView.tsx` owns curated examples, style defaults, artifact selection and the concrete playback snapshot. Its existing expressive renderer supplies Evidence review.
- `presentation/presentationModel.ts` defines the shared discriminated content union and style contract.
- `presentation/presentationFormats.ts` owns the typed format registry, stable section projection, identity metadata and local paint roles.
- `presentation/PresentationPlayer.tsx` owns current section, local scrolling, keyboard return/navigation and format presentation. The view retains the selected format when playback closes.
- `presentation/SectionEvidence.tsx` renders the complete supporting content for Briefing and Report. It reads the original section object, including artifact facts and recorded acceptance checks.
- `presentation/presentation-formats.css` owns composition, typography, local semantic paint, responsive density and reduced motion.
The current projection retains source wording and numerical qualifiers. The synthetic examples remain examples; format selection creates no new scientific claims. Future outline generation has a typed receiving boundary and a separate approval route.
## Focused evidence
`tests/presentation-formats.test.mjs` checks stable section identity, original content ownership and the three distinct navigation contracts. `tests/browser/presentation-formats.spec.mjs` exercises section continuity across formats, full-document access, end navigation, two different deck identities at desktop and compact laptop widths, reduced motion and High contrast. `tests/browser/presentation-styles.spec.mjs` verifies individual defaults, common overrides, return navigation and retained artifact picks.
These checks establish behavior and paint on the exercised browser paths. Local screenshots support visual review of settled states. Scientific validity and audience comprehension remain separate evaluations. Mobile continues to prioritize Corridor and Plate through its existing compact navigation.
## `docs/profile-preferences.md`
Source document: `docs/profile-preferences.md`.
# Profile workspace and preferences
Profile groups its navigation by the visitor's task: **Scenario & access**, **Your workspace**, and **Tools & examples**. The current section remains marked. The acting persona and environment stay visible; inspecting another person's access grid leaves that actor unchanged.
At compact desktop widths, the grouped navigation moves above the workspace so forms and the Access Grid keep their working width. Wide screens retain a side rail. Both layouts use the same mounted content and providers: a desktop resize retains the selected section, access draft and accepted preferences. The content owns vertical scrolling; the Access Grid and diagnostic log keep their local horizontal overflow where their records require it. `profile-layout.css` owns this composition, leaving the mobile Corridor/Plate receiver unchanged.
Profile offers two personal presentation choices with existing consumers. **Appearance** uses the shared theme selector; its browser-local persistence, desktop/mobile projection and colors retain the theme contract. **Informational toasts** changes ordinary confirmations and information notices immediately for this browser session. Preferences and Notifications show the same accepted choice.
Quieting informational toasts removes optional information already visible and filters later optional toasts. Warnings, errors, critical notices, all banners, error-linked feedback and explicitly persistent notices remain available. Reset notification preferences admits new informational notices again; previously suppressed notices stay discarded. Reset leaves appearance and accepted record edits intact.
`notificationState.ts` owns the typed state and reducer. The existing `NotificationProvider` retains preferences above responsive workspaces and reduces each incoming notice against the current choice. A personal display preference remains independent of record-write permissions. Reload starts with informational toasts enabled; the existing theme owner separately remembers appearance.
The Preferences panel reuses the existing compact switch and theme treatments. Unsupported density, animation, reflection, automatic-comparison and default-view settings have retired because they had no consuming behavior. Notifications states the availability of Slack, email and mobile-push delivery directly. Connections and Error Lab retain their explicit previews; they neither contact external services nor change operational records.
Focused reducer checks cover required feedback, current/future optional filtering and reset without backlog replay. Browser journeys at 1024 and 1512 pixels verify separated actor/inspection context, a fully reachable Access Grid and selected-section retention through desktop resizing. Preference journeys observe the real notification overlay, shared appearance, navigation/viewport retention, reset and permission refusals. The startup bundle check protects the mobile budget.
This contract supersedes the earlier disabled preference/routing controls. External notification delivery remains a separate future integration.
## `docs/release-workflows.md`
Source document: `docs/release-workflows.md`.
# Accepted release records
Requirements and Decisions retain local edits across workspace navigation and responsive changes. Their compact actions remain beside the source rationale. The sidebar and Map counts read the same requirement collection as the requirement list; the mobile exact-record companion reads accepted statuses.
Defer selects an explicit release. Supersede selects another active or target-state requirement, keeps the original wording, and records the replacement ID. Confirm accepts a tentative or revisited decision; Revisit returns a confirmed decision to review. **Restore original** restores that record's bundled status and release, with a new session revision. Supplied source text, rationale and dates remain historical evidence.
`services/releaseWorkflows.ts` owns typed commands, record identity, revisions and transition validation. Each accepted command rechecks `release.manage` through the current permission owner. A stale revision, unsupported release, missing replacement, self-replacement or denied role leaves the accepted record intact. These records are public planning examples; the command does not invent patient geography or clinical authority.
`releaseWorkflowContext.ts` keeps the collection in the existing browser-session owner, initialized only by its receiving module. `ReleaseRecordActions.tsx` projects the controls with the existing outlined-action and theme-token grammar. A reload begins a fresh example session. The release-plan preview shows current requirement statuses and source names within its curated packet; presentation material remains reference evidence; changing a local requirement does not publish a release or replace a source document.
Command checks cover exact-record changes, explicit targets, invalid replacements, stale acceptance, late refusal and recovery. Browser evidence covers filters/counts, navigation, accepted decisions and denied restoration. This replaces the unavailable Requirements and Decisions actions recorded in the earlier workspace audit. Future durable events remain a separate identity and storage decision.
## `docs/research/action-delivery.md`
Source document: `docs/research/action-delivery.md`.
# From controls to accepted operations
A visitor can predict what a control changes, see that result beside the selected record and recover through the operation's own inverse or reset. The [workspace assessment](#document-docs-workspace-audit-md-c4b571428b60) now records the delivered local effects. This synthesis preserves the workflow decisions and the extension points for later identity, storage and external execution.
**Supersession:** the delivered metric, Source and workflow owners replace the earlier unavailable-action and view-local-state findings. [Scoped grants, GraphQL reads and history caching](#document-docs-permission-scenarios-md-cbea28e234a3) are delivered. [Disposable Source workspaces](#document-docs-visitor-workspaces-md-49294a63218a) now resolve the earlier persistence-ownership comparison. Connector execution and verified accounts remain separate receiving goals.
## Options and adopted synthesis
| Approach | Contribution | Receiving choice |
| --- | --- | --- |
| Retire a control without a useful consumer | Reduces false affordances | Unsupported Profile preferences have retired |
| State external availability | Keeps the operation understandable | Publish, external source refresh and remote notification routes retain explicit boundaries |
| Accept a typed browser-session command | Immediate, recoverable exploration with stable record identity | Current synthetic workflow, review and metadata operations |
| Add bounded GraphQL mutations and receipts | Retains accepted Source metadata within one expiring browser workspace | Delivered for Sources; private accounts and cross-device collaboration retain a separate identity contract |
| Invoke an external system | Performs actual refresh, compute or delivery | Separate connector, credentials, cost and operating authority |
The current application combines the first three with bounded Source metadata persistence. Each supported action has a bounded outcome and a state owner. Read-only inspection, camera movement and draft typing keep their own view behavior. Personal appearance/notification choices are presentation preferences rather than record-write authority.
## Accepted interaction path
A view presents the selected record and available action. The feature command resolves the canonical record, evaluates current authority, validates the transition or fields, and commits one accepted update. Versioned editors include the revision they opened. The receiving view reads the shared projection; a denial or conflict retains the accepted record and offers its recovery route.
`services/command.ts` supplies common result/refusal and permission types. Feature owners retain their own discriminated commands, validation and transition tables. The shared policy evaluates permission; it does not replace domain legality. This implementation has no arbitrary-patch mutation or central effect dispatcher. Reopen, resume, restore, discard or save-a-copy belongs to the action family that can interpret it.
## Delivered action families
| Family | Accepted result | Permission and state owner | Boundary preserved |
| --- | --- | --- | --- |
| Specimens / biomarkers | Exact sample/order/review transitions | `recordCommands` / `recordSession`; current canonical consent, geography, resource and capability | Historical stage, dates and clinical examples retain their meaning |
| Comparisons | Resolve, Defer, Reopen and shared counts | `comparisonSession`; current scenario decision | Paired evidence and original proposal stay readable |
| Sources | Save display metadata or restore bundled metadata | `sourceSession`; `workspace.edit`, stable ID and expected revision | Provenance/authority retained; external refresh remains separate |
| Requirements / Decisions | Explicit release deferral, selected replacement, confirmation/revisit and original-record recovery | `releaseWorkflows`; `release.manage` and expected revision | Source wording, rationale and dates remain supplied evidence |
| Map | Legal sample/order/review example transitions retained by node | `mapOperations`; `sample.manage` / `review.approve` with canonical node classification | System nodes stay separate from patient records; work area is context |
| QC | Acknowledge, record hold, request rerun and reopen | `qcReviews`; stage-specific sample, analysis or release capability | Measured metrics, gate status and release hold stay intact; no invented specimen association |
| Artifacts | Check current local references; prepare, save or discard a revision proposal | `artifactWorkflows`; `analysis.run` for checks, `workspace.edit` for proposals | Original file/hash/size/acceptance remain distinct from local metadata work |
| Cohorts | Save, reopen, update, copy and remove named definitions; recompute current matches | `cohortSession` / `cohortRules`; `workspace.edit`, expected revisions and bounded typed trees | Active consent determines eligibility; saved definitions contain no copied patient data |
| Plate files | Restore/repair requests retained by physical-file identity | Plate command/overlay owners; each result keeps its consent scope | Existing demonstration executor/deadline semantics stay explicit |
| Permission experiments | Save validated grants; reset all example grants and the open grid draft | `permissionScenario` / `scenarioGrants`; Save checks `policy.edit`, Reset recovers the public experiment | Current actor/role/environment/audience, inspected person and unrelated accepted work stay intact |
| Profile preferences | Shared appearance and consumed optional informational toasts | Theme owner and `notificationState` / `NotificationProvider` | Required error/refusal feedback remains visible; remote delivery stays external |
[Shared metric comparison](#source-b6f313adb223) gives specimen displays and cohort matching the same declared at-least/at-most semantics. Target completion requires at least one metric. These typed comparisons interpret the example's declared target; they introduce no new clinical thresholds.
The feature contracts retain exact extension details: [Sources](#document-docs-source-discovery-md-40a2d04884a2), [release records](#document-docs-release-workflows-md-9eebdfbf2768), [Map/QC](#document-docs-operational-workflows-md-f6abb8b89c02), [Artifacts](#document-docs-artifact-operations-md-7ff5ea1a7629), [Cohorts](#document-docs-cohort-rules-md-bacccc83d4fa) and [Profile](#document-docs-profile-preferences-md-96585d17da7a). Session resources sit above desktop/mobile projections and initialize when received. Local workflow resources reset on reload; the installed Source workspace hydrates its expiring metadata overrides. Theme choice retains its separate browser-local persistence.
## GraphQL and view gating
GraphQL serves finite synthetic records through approved operation shapes and a server-derived showcase scenario. The shared scope kernel resolves canonical record metadata and filters permitted lists, direct IDs, nested links and counts. Access Grid edits evaluate the acting persona separately from the inspected person. History requests and caches are policy-partitioned; a scope change cancels obsolete work, and denied reads keep their own result rather than exposing an unrestricted fallback. Resetting example grants clears the accepted grant log and derives the seed key for the current selection. Existing scope reconciliation restores its permitted projection, including an already successful cache partition, without clearing records, file recovery or exploration. The log remains bounded to 64 saved cell-change entries: repeated changes count, no-op saves add none, and overflow preserves the accepted scope and draft with reset as recovery.
These controls demonstrate permission behavior. Selectable personas and registered queries do not verify a real visitor's identity. Private records or real multi-user writes require a separate verified-session design and acceptance decision. Readable context and denial explanations remain available where the policy permits them; hiding a write affordance alone never enforces the operation.
Source mutations now expose named operations with record ID, expected version and idempotency key. The server supplies an origin-bound disposable scope and acceptance time, reuses domain validation and simulated policy, and commits the accepted receipt and projection together. Typed refusal/conflict returns preserve the draft. Verified accounts remain a distinct boundary for private records or shared collaboration.
## Database rows follow a durable receiving job
The PostgreSQL and retained MySQL adapters serve Plate histories and, after explicit setup, isolated Source metadata workspaces. The owner selected [disposable browser workspaces](#document-docs-visitor-workspaces-md-49294a63218a) for that persistence boundary. Other accepted workflow families keep their local owners.
Four separate tables hold workspace ownership/lifetime, bounded Source revisions, accepted receipts/history and migration ownership. A random protected cookie supplies sandbox possession; the exact normalized origin binds every workspace operation. Current scenario actors remain explicitly simulated. Absolute expiry, reset, quotas and exact retries keep the public example scope finite. The canonical baseline, consent, geography and grants retain their existing owners.
The [workspace contract](#document-docs-visitor-workspaces-md-49294a63218a) records transaction, request and recovery boundaries. Its real PostgreSQL and retained MySQL checks observe locking, concurrent version/idempotency/quota behavior and rollback. This expiring example history supports inspection; a permanent clinical audit claim requires its own identity, retention and operational evidence.
SQL views may later package a useful read projection. A shared application database login remains distinct from a browser persona, so database view privileges cannot replace application identity and scope. The public path uses PostgreSQL base-table adapters behind the ordinary Node server.
## Evidence and continuation
Owner cases establish exact-record acceptance, refused/stale/malformed commands, domain recovery and original-evidence preservation. Browser journeys establish visible outcomes, fresh accepted-source use, navigation and responsive retention. Scoped API cases add direct/nested-read agreement and cache isolation. Each family uses the applicable subset; the workspace store adds actual-engine rollback and concurrent-version observations for its activated Source writer.
The [permission research](#document-docs-research-permission-behavior-md-0592cad58a64) retains the primary-source basis. Compact composition now gives those accepted operations task-specific [working layouts and returns](#document-docs-workspace-layout-md-b161445e3297). [Grant-experiment reset](#document-docs-permission-scenarios-md-cbea28e234a3) provides local recovery without restarting accepted work. It remains available in Viewer/read-only scenarios because it restores the finite public experiment; ordinary grant saves retain their authorization checks. [Follow a sample](#document-docs-research-guided-exploration-md-ad62b036d202) now demonstrates three working scenes with optional playback and manual takeover. AI assistance remains a separate design decision, including any future selected-sample presentation flow.
## `docs/research/component-loading.md`
Source document: `docs/research/component-loading.md`.
# Local feedback for primary panels
Visitors should see which record they selected immediately, understand genuine waits in that record's panel, and keep exploring the surrounding scene. The recommended first repair keeps the Sample history tray present while its decorative thread and reveal run, then places real history-request feedback beside the selected record. A restrained geometric placeholder is useful when a primary panel has no usable content; it should dissolve as content becomes ready.
**Status:** research supporting the selected-history loading experience. The first focused repair is recorded in the [loading contract](#document-docs-loading-experience-md-9fbe539c61fa): continuous tray, parallel reveal, keyed primary source strip and real-request geometric activity. This supersedes the proposal-only status; the audit below preserves the observed pre-repair mechanism. A full geometric skeleton remains conditional on a future panel lacking usable content. The earlier source audit and production timing observation used the same loading and Plate owners. Those historical observations explain the decision; the [loading contract](#document-docs-loading-experience-md-9fbe539c61fa) names the current owners and receiving checks. React is pinned to 18.3.1; the existing Motion library, typed themes and CSS composition are sufficient.
## Earlier mechanism audit
The table and timing probe below describe the pre-repair implementation. In particular, the MySQL-only cleanup and plate/well cache key record that earlier state. Current history ownership uses a permission-scope partition plus plate/well identity, and each selected SQL adapter owns request cleanup. The [loading contract](#document-docs-loading-experience-md-9fbe539c61fa), [permission contract](#document-docs-permission-scenarios-md-cbea28e234a3) and [PostgreSQL contract](#document-docs-postgresql-md-a7cc27814ec8) describe the delivered receivers.
| Receiving surface and source owner | Behavior observed before repair | Proposed feedback at that time |
| --- | --- | --- |
| Initial HTML, `App.tsx`, `DeferredView.tsx`, `loading/PlateLoading.tsx` | Entry and desktop chunks must download/evaluate. Initial HTML already paints a plate/grid composition; Suspense handles the desktop boundary and a failed chunk offers Reload. A ready overlay dissolves over 900ms, with an 1100ms removal fallback. | Keep the existing primary-workspace treatment. Content becomes usable when mounted; the overlay remains pointer-transparent. |
| First mobile Plate, Corridor controls/details and exact linked record | `React.lazy` imports in `MobileShowcase`, `MobileCorridor` and `MobileCorridorDetails` use `DeferredView`. Later mobile Plate visits retain the mounted view. | A scoped code-loading fallback belongs inside the receiving panel. Cached/mounted visits stay immediate. |
| Selected well history, `services/plateHistory/{context,request,read}.ts*` | One actual browser data fetch: approved GraphQL operation, complete DTO validation, key `plateId/wellId`, successful workspace cache. An 8-second client deadline and abort/current guard bound publication. Server GraphQL has a 5-second deadline and request-owned MySQL cleanup. | Keep source and retry information local. A selected-history request must be distinguishable from examples already available in the scene. |
| Desktop `PlateScene3D` → `ResultTray` | The tray mounts after the camera reaches `locked`. `TrayRecord` is synchronous: `resolveResult`, `athenaPosture`, `readinessAnswers` and related projections derive local values. On record changes, `AnimatePresence` waits for exit; a thread-led clip reveal and item staggering delay visible ink. | Treat this as selection/reveal motion. Show record identity/structure immediately; let decorative motion follow without a loading claim. |
| Mobile `CompactResultRecord` and `WellDetail` | Props select an existing result/sample. Topic and result changes are local; selected-well requests independently update `history.stacks`. | Direct local update, with the same selected-history status where a real request is pending. Keep the readable companion below the scene. |
| Profile access grid, `ProfileView` / `accessService` | Reads use an existing 180ms demonstration timer; writes update an in-memory overlay immediately, then resolve after 260ms. Read cleanup ignores superseded responses; Save has independent `saving` state. | Existing local status is enough. A future service migration must add explicit rejection/identity recovery; new loading ornament would amplify a simulated wait. |
| Plate file/query actions, `plateOverlay` | Restore is accepted synchronously and remains pending against the example clock. A partition repair completes after the existing 2400ms demonstration timer; rebuild remains queued. Timers are cancelled on provider unmount. | Domain status (requested, repairing, queued) belongs to the action. These are not panel-download states or measured live-storage progress. |
| Clipboard and file actions | `ResultTray` awaits the browser Clipboard API and reports success/failure. The current download estimates and export-eligibility labels are local calculations, not active file transfers. | Small action feedback. A future file-download owner must supply its own completion semantics before reporting progress. |
| Other chapter records, topic selectors, local edits, table filters, camera movement | Canonical in-memory records, synchronous projections or Motion/RAF work. Camera promises represent animation completion, not data readiness. No current `startTransition` or `useDeferredValue` owner was found. | Keep these operations direct. Profile demonstrably slow synchronous work before adding scheduling or placeholders. |
At that audit, the source rail distinguished stored/example, checking, missing, empty and unavailable, and offered Retry. It sat outside the desktop tray, where a visitor could miss the request context. The hook returned a default `loading` phase while idle/inactive and resolved cached selection through an effect. These findings motivated the delivered explicit activity and keyed readiness projection.
### Observed Sample history delay
A production Chromium probe selected Sample history, waited for the tray, then hovered C3 without pinning or requesting history. It observed **zero GraphQL requests**. In one settled desktop run, the tray mounted after roughly **0.89s**, became opaque around **1.10s**, record DOM appeared around **0.21s** after hover, the header began showing readable ink around **0.82s**, and the clip opened fully around **1.26s**. These are local observations, not cross-device performance claims or acceptance thresholds.
Source explains the sequence: 90ms hover intent; summary/record exit of 100–120ms; `THREAD_DRAW_S = 0.46`; body start at thread time + 0.1s; a 0.5s clipped reveal and staggered children. The camera has its own 130ms wind-up and spring completion. This establishes a material animation-origin delay even when records are available. It leaves real hosted latency and low-end-device rendering cost open for their own observations.
## Four treatments and their fit
| Option | Useful property | Cost or boundary | Decision |
| --- | --- | --- | --- |
| Progress bar | Familiar place to track a bounded operation; an indeterminate line can signal activity with little space. | The current fetch supplies no fraction or bytes-complete denominator. A global bar would misrepresent a local request. | Reserve determinate progress for measurable work. Use an indeterminate rail only if it reads better than the small local indicator in the panel. |
| Small throbber with a short label | Names a specific pending request without displacing working content. | Repeated spinners compete with the 3D scene and imply that local selectors need processing. | Preferred for background checking beside existing content: “Checking C3 history…” in one scoped status rail. |
| Shape-matched skeleton | Reserves a primary panel's footprint and previews its hierarchy. | A dense copy of every row creates noise; showing it over useful data adds churn. Exact response shape may vary. | Use only when the primary receiving panel lacks usable content: heading strip and a few broad content blocks. |
| Restrained geometric/Mondrian panel, then dissolve | Connects the existing loading art to the panel's structure using a few theme-colored rectangles. | Decorative novelty is a design hypothesis; it has no established advantage over a conventional skeleton here. Random blocks can imply an error or hide the expected content structure. | Synthesize with the skeleton: stable, panel-shaped regions, low contrast, one subtle movement, short nonblocking exit. Keep it exclusive to primary-panel waits. |
The recommended combination is **immediate stable structure + one local request receipt + a geometric skeleton only for truly absent content**. It draws on the existing plate loading vocabulary without replaying the full startup composition for every selection. Existing results remain readable while a source is checked. Once content is ready, a proposed 150–200ms opacity dissolve may accompany its first paint; that duration is a design trial, not a forced wait or research-derived threshold. Reduced motion shows the ready content directly. Fast/cache hits earn no additional ceremony.
## Evidence translated into implementation
| Evidence | What it establishes | Receiving decision and transfer limit |
| --- | --- | --- |
| [React 18 Suspense](https://18.react.dev/reference/react/Suspense) | Lazy component loading activates the boundary; data fetched in an effect does not. Nested boundaries define reveal groupings. | Keep `DeferredView` for code-loading. Pass explicit history state to the tray; wrapping an effect-driven fetch in Suspense would leave its wait unobserved. |
| [React Effects](https://react.dev/reference/react/useEffect) | Dependencies determine synchronization; cleanup runs before re-synchronization and unmount. The data-fetching example prevents stale response publication. | Preserve the existing abort/current guard and timeout. A new visual status consumes the request owner rather than starting a second fetch. |
| [React 18 transitions](https://18.react.dev/reference/react/useTransition), [deferred values](https://18.react.dev/reference/react/useDeferredValue) | Nonurgent rendering can yield to input; deferral does not make the underlying computation or network faster. React 18 transition marking covers synchronous state updates in the scope. | Use measured render evidence before introducing these hooks. Neither `isPending` nor a camera promise represents GraphQL completion. Retain urgent controls outside deferred work. |
| [React context](https://18.react.dev/reference/react/useContext), [external-store snapshots](https://react.dev/reference/react/useSyncExternalStore) | Context changes propagate to consumers; an external mutable store requires stable snapshots and subscription cleanup. | Keep a narrow keyed request owner and pass derived status as props. Context carries a stable cache/service handle, not an app-wide loading boolean. A new external store belongs to demonstrated multi-consumer needs. |
| [WAI status messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html), [aria-busy](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy), [progressbar](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) | Status can be announced without moving focus. Busy identifies incomplete updates. Indeterminate progress omits a fabricated current value. | Name the selected pending work once; scope busy to the result region. Put its concise status outside the busy subtree if it needs immediate announcement. Decorative geometry is hidden from assistive technology. |
| [Nielsen response-time guidance](https://www.nngroup.com/articles/response-times-3-important-limits/) | Classic 0.1/1/10-second bands distinguish direct response, interrupted flow and extended waiting. | A visible response should begin with selection, not after a one-second animation chain. These historical heuristics are observation guides; they do not justify inserting delays. |
| [NN/g skeleton comparison](https://www.nngroup.com/articles/skeleton-screens/), [progress feedback](https://www.nngroup.com/articles/progress-indicators/) | Feedback clarifies that work is happening; shaped placeholders communicate expected layout. Animation can also distract. | Adapt the layout-preserving principle to a primary panel. NN/g's skeleton article focuses on full-page loads; this smaller application is a bounded design inference, not direct experimental proof. |
| [Carbon loading guidance](https://www.carbondesignsystem.com/building-blocks/core/components/loading/guidelines) | Local indicators can sit near their triggering action; multiple simultaneous indicators can overwhelm. Skeletons suit progressive content. | One indicator belongs to the receiving task. Carbon's suggested time threshold differs from other heuristics; the real owner/state governs the first implementation. |
| [Chrome interaction guidance](https://web.dev/articles/optimize-inp) | Input delay, event processing, and presentation delay have different causes. Script evaluation and long tasks can postpone the next paint. | Measure these separately from a CSS/Motion reveal. A skeleton cannot paint through a blocked main thread; optimize a proven expensive projection or yield work at its real owner. |
All sources were consulted during this research. The React 18 archive matches the installed major version; current documentation contributes only stable contracts already available in that version. Browser observations establish the local rendering sequence. The visual preference for a muted geometric placeholder remains a proposal to compare in the receiving panel.
## State and ownership contract
Keep request identity separate from animation identity. A selected read carries the current permission-scope key, plate ID, well ID and request attempt. The [cache owner](#source-b8b7b608e5d1) partitions successful histories by scope, then keys each history by plate and well. A scope change cancels obsolete requests and selects its own permitted projection; denied or missing records cannot reuse another scope’s history. A future change to source or dataset version must also enter identity and invalidation before reuse. The permission scenario chooser remains demonstration policy rather than server authentication.
The request owner projects idle/loading/ready/unavailable activity, while its current scope and blocked-read results govern denial and missing records. Keep these policy outcomes distinct from transport failures. Ready contains source, results and missing metadata; empty/missing are meaningful ready outcomes rather than extra independent flags. The panel receives a typed projection of this state, the requested identity and a Retry command. Rendering never owns the request or a duplicate data cache.
- **Selection:** publish the chosen identity immediately. Cancel the preceding request and only accept the current attempt. The current request helper already supplies the essential lifetime guard.
- **Pending with useful content:** retain correctly identified examples or same-key cached data with explicit source. A previous well's record must retain its old identity until replaced; it must never silently acquire the new well label.
- **Pending without useful content:** reserve the panel's geometry, show its heading and geometric skeleton, and keep scene navigation available.
- **Cache hit:** publish ready directly. A spinner caused by an effect-only cache lookup is avoidable churn; establish one keyed ready projection rather than introducing a minimum display duration.
- **Failure/deadline:** settle to a local unavailable receipt with Retry; retain explicitly identified examples where policy permits them. Retry belongs to the current key. Raw transport/database detail stays out of visitor copy.
- **Denied:** show the actionable permission outcome from its policy owner. An error-shaped network failure cannot establish denial. The current read policy already governs cached and example fallback visibility; a denied result stays withheld from the receiving projection.
- **Cancellation:** abandoned selection or hidden/unmounted view stops outstanding work and visual timers silently. A subsequent selection owns its own state. The current deadline remains a recovery boundary, not a progress denominator.
- **Ready:** make content available immediately. Any decorative exit uses a separate, short, cancellable reveal lifecycle and never gates interaction or data publication.
**Supersession:** The later [shared accepted-state and scoped-cache owners](#document-docs-workspace-audit-md-c4b571428b60) now retain records across responsive workspaces. The keyed request approach remains proportionate to the app. Add a query library or external-store subscription when concurrent subscribers, invalidation or real server mutations make that cost worthwhile; a second cache beside the current one would obscure ownership.
## First focused repair and evidence
1. **Make the tray continuous.** Reserve its current geometry when Sample history is requested; show the selected identity or existing summary while the camera swings. Keep the camera spring, thread, ink hierarchy and dark/light/contrast palettes. Update result identity/content promptly and run the thread/reveal decoration in parallel. An available record should not spend the full thread + clip + child sequence invisible.
2. **Connect the actual request.** Pass a selected-history status projection from `LanesView` and `MobilePlate` into the primary record companion. When hover previews a different well, continue identifying that local example rather than attaching the pinned well's request label. Give the one visible request receipt and Retry a clear owner, avoiding duplicate live announcements with `PlateHistorySource`.
3. **Add only the missing placeholder.** A small shared loading visual accepts an explicit mode and label; it has no fetch, timer-based progress or business logic. Use its geometric skeleton only for an empty primary panel, and its small inline state when content is already useful. Preserve the existing initial workspace loading treatment.
4. **Prove the boundary.** Extend existing request tests for replacement/cancellation/deadline where needed. Browser journeys hold an actual history response, select another well, release responses in reverse order, retry a failure, revisit cache and exercise ready-empty/missing. Observe identity, readable status and terminal state. Test local hover with zero reads, rapid record changes, theme modes, reduced motion and mobile companion geometry. Preserve startup payload/deployment checks if shared imports change.
A local production timing probe already establishes the animation-origin delay; its cycle-scoped script and raw output remain ignored local artifacts. Existing `tests/browser/plate-history.spec.mjs`, `loading.spec.mjs` and Plate journeys provide the durable test owners. The repair should add only the assertions needed to distinguish truthful waiting and prompt record selection. Extensive performance instrumentation, dependency replacement, global loading overlays and a redesign of unrelated panels remain outside this first tranche; a measured residual delay can reopen the appropriate owner afterward.
## `docs/research/guided-exploration.md`
Source document: `docs/research/guided-exploration.md`.
# Guided exploration: follow a sample
A visitor can watch the existing Corridor and Plate scenes explain one sample, take over at any point, and return to the walkthrough from the header. The research was assessed against the application at `682a33f`. It records the implementation contract; receiving checks establish delivery.
## Decision and alternatives
Combine a small first-arrival invitation with a three-scene demonstration in the working interface. **Watch walkthrough** advances after the receiving scene has settled and a short reading interval. Selecting a question leaves advancement with the visitor; reduced-motion mode offers **Explore step by step**. Both offer the same subjects, visible progress, Back/Next, and a direct way to take control or dismiss. Header replay remains available. The invitation sits outside the navigation hierarchy and appears after application loading.
| Option | Useful contribution | Fit for this pass |
| --- | --- | --- |
| Opening explanation or question cards | Makes the purpose recognizable quickly | Keep one short introduction and an immediate exploration choice |
| Continuous automatic tour | Shows the existing camera, history and record animations | Start only after an explicit Watch action; divide it into observable scenes |
| Contextual guided sample | Connects instructions with the exact record and controls | Use as the main composition; hands-on exploration remains available throughout |
| Task checklist | Makes a long learning sequence recoverable | Three scenes and header replay provide enough structure here |
| Conversational guide | Could answer individual questions | Remains with the separately scoped AI work |
The goal is orientation and an engaging first encounter. Learning gains and completion rates remain questions for visitor observation, rather than claims implied by the animation.
**Developer docs** opens the independent `/docs/` reading view in a separate tab.
The desktop sidebar, Guide invitation and mobile information dialog share the
same labelled link. In Guide and mobile information, it sits directly above the
copyright credit. The current scene, Guide position and unsaved editors remain
mounted in the application tab. The independent foundation/repository invitation
joins this location after its publication destination has been verified; the
working local documentation link remains available during that handoff.
## Evidence that changes the design
| Evidence and class | Consequence for this implementation | Transfer boundary |
| --- | --- | --- |
| Carroll and Rosson describe task-oriented exploration and the tension between accomplishing work and investing in instruction. [Original chapter, 1987](https://research.cs.vt.edu/ns/cs5724papers/4.mental.mental.carroll.paradox.pdf) | Teach through the actual scene and offer immediate control; keep instruction close to the action it explains. | Early office-software observations inform a design hypothesis for this scientific showcase, rather than a universal account of every visitor. |
| Pirolli and Card model the value of information against the effort of finding and processing it. [Original ACM paper, 1995](https://chi1995.acm.org/proceedings/papers/ppp_bdy.htm) | Name the question each scene helps answer: workflow, reason for reanalysis, available files. Preserve the selected sample as visitors move between these views. | Information-foraging theory supplies a useful navigation lens; it does not prescribe this exact three-scene interface. |
| Apple recommends brief, optional, interactive onboarding, contextual guidance, and an easy way to revisit a skipped tutorial. [Current Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/onboarding) | Offer Watch and stepwise routes after loading; preserve dismissal and header replay; show guidance beside its receiving scene. | Platform guidance informs interaction choices, not a measured outcome for this application. |
| NN/G describes tutorials that interrupt a current task and require remembering instructions away from their controls. [Original practitioner observations](https://www.nngroup.com/articles/onboarding-tutorials/) | Returning browsers enter their requested view directly. Replay stays voluntary, and the guide leaves the working scene available. | These observations challenge forced onboarding; they do not establish that every optional showcase tour is ineffective. |
| A registered conceptual replication with kidney-function material found no significant cognitive-load, retention or transfer benefit from segmentation. [Soicher and Becker-Blease, 2020](https://onlinelibrary.wiley.com/doi/abs/10.1111/jcal.12485) | Use pauses and short scenes for visitor control, interruption recovery and readable pacing. Keep comprehension claims modest. | This health-education study bounds transfer from multimedia-learning findings; it does not test this interface. |
## The three receiving scenes
1. **Follow the work.** Show the real Corridor and its existing spring transition into an informative view. Explain that the lanes connect processing steps and their supporting records. The visitor can orbit or move the scene directly.
2. **Understand a repeated analysis.** Open C3 in Sample history and select its R2 annotation refresh. The bundled C3 example distinguishes reanalysis of existing reads from a new physical run: R2 updates annotation, while R3 represents a separate orthogonal confirmation in progress. Caption the currently returned record and keep its source status visible.
3. **See what data is ready.** Stay with the selected result and reveal Files and lifecycle information. This connects reused files, availability and restoration windows with resource choices. The visitor can continue exploring the existing controls. Exact cost estimates, patient lookup and actions that are not supplied by the current record remain outside the guide's claims.
The guide changes navigation, selection and presentation only. Restore, rebuild, metadata saves, grants and other accepted commands remain explicit visitor actions through their existing owners. Completion hands back the current scene; it preserves accepted work and the selected sample.
## Source ownership and receiving APIs
| Existing owner | Integration contract |
| --- | --- |
| `services/exploration/ExplorationProvider.tsx` | Share scene intent, selected well, result focus and Plate options above responsive workspaces. A guide request selects Plate, then C3 and the intended available result. The first compact Plate selection otherwise supplies its own B4 default. |
| `DesktopWorkspace.tsx` | `Shell` currently owns the active section and exact-record return context. A typed guide receiver selects Lanes while retaining the ordinary navigation path. Header replay enters the same guide owner. |
| `components/views/LanesView.tsx` | Receive the guide's Corridor preset and Plate selection intent through owned callbacks. `presetMotion`, selected Corridor card/lane and compact Plate rail are local presentation state. |
| `components/mobile/MobileCorridor.tsx` | Receive equivalent scene intent through its local camera, lane and view owners. Its camera differs from the shared desktop control; assigning the desktop camera alone cannot animate the compact scene. |
| `components/corridor/useCorridorPresetMotion.ts` | Reuse the cancellable spring and nearest-yaw projection. A narrow completion signal can acknowledge the current guide request after the movement settles. Direct input cancels the requested movement. |
| `components/plate/PlateScene3D.tsx`, `sceneTransition.ts` | Setting `plateUi.upright` already runs the wind-up, spring entrance and extrusion. Expose readiness through a typed callback at the settled phase. Existing DOM data attributes remain browser-observation hooks. |
| `services/plateHistory/context.tsx` | The current well, policy scope and request phase decide which history can be shown. Loading holds progression. A terminal unavailable, denied or missing result keeps its recovery state visible and hands control back; the guide preserves the current permissions. |
| `components/plate/ResultTray.tsx` | Desktop already presents Why, Files and lifecycle columns together. Compact records own a local Why/Files/Lifecycle/Sample selection; a bounded section request can reveal Files without a simulated click. |
| `components/mobile/MobilePlate.tsx` | Continue using shared well/result selection and its actual compact record. Bring the receiving record into view through component-owned refs after it is ready. |
| `services/recordNavigation.ts` | Use canonical record targets if a later branch opens a supporting source. Result files stay with their actual Plate record; the guide does not invent an association with the separate Artifact gallery. |
The guide needs a small typed state owner and a finite scene/request union. Existing React and Motion capabilities cover this route. Scene receivers report the current request's readiness and receive cancellation; a tour dependency or a second scene renderer would add ownership without improving this bounded journey.
## State, pacing and recovery
Keep guide progress separate from accepted records, permission scenarios, appearance and hosted Source workspaces. A request generation identifies each explicit scene choice. A separate interruption marker cancels pending guide-owned selection after Pause or direct input; responsive receivers share the current request. Exit removes that request from active receivers. Each receiver cleans up its timer or animation when superseded. These choices apply React's effect cleanup and state-ownership guidance to the real timing boundary. [React effects](https://react.dev/learn/synchronizing-with-effects), [state structure](https://react.dev/learn/choosing-the-state-structure).
Watch mode starts its reading interval after the scene's readiness acknowledgement. A timer alone cannot establish that the selected history arrived or the camera settled. Direct pointer, wheel or keyboard interaction, window blur, a hidden document and reduced-motion preference pause automatic progression. Stepwise controls retain access to the same content. A denied or unavailable source exposes its existing outcome and recovery controls instead of advancing as though the expected record had loaded. Pause, resume and dismissal remain visible near the guide; motion control follows the same intent as the [W3C pause/stop/hide guidance](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html), while explicit-start playback has its own activation condition.
First-arrival recognition uses one versioned, allowlisted browser preference. Record the visit once the guide owner mounts; retain the initial render decision in memory so persisting that flag does not instantly remove the invitation. Returning browsers open Lanes/Corridor unless a [shared application address](#document-docs-shareable-navigation-md-bcfb7b016c1b) selects another view. Browser Back/Forward closes the guide before applying that bounded view choice. The flag records presentation preference, not identity, authentication or participation in a clinical workflow. Read/write failures fall back to an in-memory choice for the current application lifetime. Browser-local storage may be cleared or unavailable, and differs by origin; a different browser or deployment origin can therefore receive the invitation again. [MDN localStorage contract](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
## Proportionate receiving evidence
Observe first-arrival invitation, dismissal and replay; the actual Corridor transition; C3's selected returned history and Files handoff; and the visitor's ability to take control. Exercise one delayed history response followed by Exit or a newer selection to establish that stale readiness cannot resume playback. Preserve an accepted edit while navigating through the guide and crossing a compact/desktop boundary. Check reduced motion, denied/unavailable history and blocked local storage as distinct receiving conditions. A settled desktop and phone capture should show readable guidance beside an operable scene. Retain the existing startup-bundle and production build checks because the guide crosses the initial rendering boundary.
These checks establish working navigation, cancellation, state retention and visual fit. A later brief visitor observation can assess whether the three questions make the application easier to understand; it remains separate from executable delivery evidence.
## `docs/research/high-contrast-wells.md`
Source document: `docs/research/high-contrast-wells.md`.
# High contrast Plate cues
## Receiving decision
High contrast gives failed QC a restrained diagonal face mark in every lens, and gives the existing green/violet category pair a gold/blue projection with sparse category marks. Dark and Light keep their existing colors, gradients and patterns. This is a small Plate experiment for review and community feedback, with the receiving evidence described below.
The receiving task is to distinguish a category while scanning small wells and result discs. The selected record and labelled legend still explain its meaning. No theme or simulation establishes a universal color-vision guarantee.
## Evidence that changes the design
| Evidence and class | Design consequence and limit |
| --- | --- |
| The [National Eye Institute](https://www.nei.nih.gov/eye-health-information/eye-conditions-and-diseases/color-blindness/types-color-vision-deficiency) distinguishes deuteranomaly from deuteranopia and describes difficulty with particular red/green shades. Official clinical summary. | Test actual rendered colors instead of treating every green/purple pair as equivalent. Hue names alone do not predict whether these particular categories will be distinguishable for a particular visitor. |
| [Machado, Oliveira and Fernandes (2009)](https://pubmed.ncbi.nlm.nih.gov/19834201/) model normal vision, anomalous trichromacy and dichromacy in one framework, with experimental evaluation. Primary research. | Simulation is a useful design probe. Its population/model assumptions and a visitor's actual perception remain distinct; a full-severity rendering does not demonstrate every deuteranomaly severity. |
| [W3C technique G111](https://www.w3.org/WAI/WCAG22/Techniques/general/G111) pairs color and pattern and repeats both in the legend. Official guidance. | Generate face and legend from one paint projection. Text remains available in the key and selected record; the marks add a second visual channel without a new label on every well. |
| [W3C non-text contrast guidance](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) calls attention to adjacent surfaces, gradients and thin anti-aliased marks. Official guidance. | Inspect the actual 26–28 px faces and small legend swatches. A nominal color calculation alone does not establish that a projected, shaded mark remains readable. |
| [Chrome's rendering tools](https://developer.chrome.com/docs/devtools/rendering/apply-effects#emulate-vision-deficiencies) provide deuteranopia and achromatopsia emulation. Official implementation documentation. | Capture the same Plate under those two probes. The test tool's available modes are the evidence boundary; it does not supply a graded deuteranomaly preview. |
## Options and synthesis
Hue-only adjustment keeps the scene quiet but leaves categories dependent on color. A repeated diagonal or dotted texture is stronger at larger sizes, but the existing frost and consent hatch already have domain meanings and dense texture becomes busy across a plate. Zoom-only signifiers improve inspection after selection while leaving the initial overview unchanged. Large letters or icons would compete with well coordinates and the selected-result labels.
Use a single diagonal for failed QC, combined with the existing glossy face. This result-level cue remains available as the visitor changes lenses and does not require every well to gain a symbol. Consent holds and cancelled faces take priority; frozen-file texture stays visible beneath the quality mark. Status labels and the key describe the failure.
The additional category-pair experiment uses a small dot or short bar:
| Source hue | High contrast face | Additional cue | Receiving categories |
| --- | --- | --- | --- |
| Green `#34d399` | Gold `#ffd166` | Center dot | Orthogonal result, Standard storage, Queryable |
| Violet `#a78bfa` | Sky blue `#87c9ff` | Short center bar on an otherwise unpatterned face | Reanalysis; Glacier Flexible keeps its existing frost instead |
Marker ink is `#06101d`. The failed-QC diagonal suppresses the optional dot/bar on that face, keeping one foreground mark. Other category colors retain their current High contrast derivation. Gold may approach other warm categories, and blue may approach longitudinal results; the face mark is the additional distinction. Existing consent hatching, cancelled hollow faces and frozen-file textures take precedence. Dot/bar patterns mean the category shown in the current lens. The separately owned diagonal means failed QC across lenses; the key names that distinction.
`stackLens.ts` owns the mode-specific category projection, pattern precedence and CSS face painting. Its typed paint data feeds desktop overview wells, 3D history, mobile board and both legend presentations. `usePlateColors` receives the same color mapping for record companions. No additional renderer, dependency or camera state is introduced.
## Observation and next receiver
Focused checks compare affected paints with their labelled keys, carry the failed-QC mark across lenses, preserve consent and storage-pattern precedence, and retain the established Dark/Light pair. A cycle-scoped comparison checks every status/kind/lens combination against the accepted pre-change paint function in Dark and Light. Browser observations cover the High contrast desktop and compact views, mode switching and selected history. The local Chromium captures show the dot/bar distinction on the 390 px board and the failed-QC diagonal in its key and selected history under ordinary, deuteranopia and achromatopsia rendering. Warm categories move toward similar yellows under the deuteranopia probe, making the dot useful. Steep 3D angles shrink every face mark; the existing camera, zoom and selected record remain the inspection route. These screenshots are diagnostic artifacts, not perceptual validation or a conformance certification.
Invite feedback on three concrete questions: is the failed-QC diagonal useful at ordinary zoom; do the dot/bar category marks and their key make the gold/blue pair clearer; does any cue become distracting across the plate? Revisit cue size or the narrow palette pair from that evidence. Broader category redesign and graded color-vision evaluation remain separate decisions.
## `docs/research/input-boundaries.md`
Source document: `docs/research/input-boundaries.md`.
# Bounded application inputs
The application accepts useful showcase edits through named, bounded receivers while retaining the current visual experience and ordinary Node/PostgreSQL path. This assessment follows the current inputs through their runtime owners. Synthetic records and selectable showcase roles remain distinct from future verified identity.
The 2026-11-17 follow-up supersedes the earlier conclusion that the delivered input controls completed the bounded input assessment: per-request bounds were present, while parallel requests could still start an unbounded amount of work. The focused follow-up adds shared admission across both GraphQL routes. The earlier text, command, cohort and document-policy findings remain accepted.
## Inputs and receiving boundaries
| Input and receiver | Observed boundary | Decision |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Source title, summary and tags → cards, details and linked titles | React renders text. Commands admit bounded fields with canonical identity, current policy and expected revision; baseline provenance stays immutable. | Preserve valid plain text, including HTML-looking strings. Hosted acceptance and retry remain with the Source workspace owner. |
| Pipeline configuration manifest → Source metadata form | The record describes a configuration source; its form edits title, summary and tags. | Keep metadata separate from execution. A future manifest import needs an explicit schema and execution boundary. |
| Cohort palette/drop/link operations → recursive canvas and expression | Iterative draft admission bounds size, depth and cycles before recursive consumers. Save separately validates a complete definition. | Retain 128 cards/eight levels and preserve the previous draft on refusal. Labels may remain temporarily empty while editing. |
| Loading bootstrap and reload control → browser execution | Startup hashes the exact reviewed inline bootstrap. Reload uses an event listener. | Retain the production CSP and named bootstrap; runtime text contributes neither executable markup nor policy values. |
| GraphQL documents, IDs, cursors, variables and scenarios → registered operations | Each route allows reviewed documents, bounds bodies to 16 KiB and responses to a five-second deadline, rejects batches, and bounds IDs/pages/cursors/scenarios. The installed Yoga body limiter counts streamed bytes as well as Content-Length. | Preserve existing owners. The operation allowlist fixes query shape; a query-cost/depth dependency adds little to this finite document set. |
| Parallel GraphQL requests → parsing, resolvers and short-lived database connections | Valid requests previously entered independently. Even WorkspaceStatus checks the installed schema through a database transaction. Creation throttling limits new workspaces, rather than all concurrent reads. | Share an eight-request in-flight budget across both routes before parsing/storage. Refuse excess work immediately; keep admitted work counted through its actual cleanup. |
| Workspace cookie and commands → disposable Source storage | A random token is held in an HttpOnly, SameSite=Strict cookie; HTTPS uses the Secure host-prefixed cookie. Storage owns its verifier and normalized origin. Fresh policy, revisions and immutable receipts govern writes. | Preserve origin/Host checks, explicit request marker, fixed lifetime, finite quotas and exact retry. A selectable scenario remains demonstration policy; verified private-data authorization has its own receiver. |
| Values → PostgreSQL/MySQL adapters and setup | Values use placeholders. Table names come from owned lists and numeric limits from server constants. Setup runs separately from requests. | Retain separate read/write transaction owners, explicit migrations and atomic projection/event/receipt updates. |
| Links and generated expressions → display, navigation or clipboard | Navigation resolves canonical IDs; SVG references target local elements; file copy locations come from canonical records. Expressions render as text. This pass found no user-controlled execution or HTML insertion sink. | Keep each receiver explicit. Future external links need a scheme/host policy; future executable queries or configuration need their own validation boundary. |
| Browser storage and search | Appearance storage accepts named modes; search filters current collections. | Retain these bounded projections. Imported state needs owned parsing before joining accepted state. |
## Shared request admission
`server/security/request-admission.mjs` owns one in-flight counter. `scripts/serve.mjs` passes the same owner to the read API and visitor workspace API. Eight requests can be active; an excess request receives **503 Service Unavailable**, a one-second `Retry-After` hint, `Cache-Control: no-store` and a bounded GraphQL error. The owner keeps no queue, client identifiers, request bodies or token map. Eight is an initial conservative showcase budget, not a measured hosting throughput claim; the named constant provides the tuning point if observed use warrants it.
Each API registers admission inside its deadline wrapper and outside its owned handler/cleanup. A deadline can return a timely response while underlying work is still finishing; the slot remains occupied until that work settles. Success and failure release their slot in `finally`. Existing connection cancellation and transaction deadlines retain their separate roles.
The Source client already treats temporary HTTP failure as an unconfirmed request, retains the draft and retries with the same command identity. Read clients retain their existing retry path. Static files remain available independently of this API budget. This process-local boundary controls concurrent application work; it does not provide per-person fairness or provider-wide denial-of-service protection. Hosting-level traffic controls belong to the deployment receiver, especially if the app gains multiple processes or verified accounts.
## Production document policy
`server/security/document-policy.mjs` derives the CSP once at startup from `dist/index.html`. It recognizes the trusted `initial-load-bootstrap` and stops startup for review if another inline script appears. Hash bytes include the script's exact whitespace. Same-origin assets and requests remain allowed; Google Fonts retains its two stylesheet/font origins. Inline styles remain necessary for the current React geometry, camera transforms, theme variables and motion.
The policy disables plugin objects, document base changes and child frames, and confines form targets to the same origin. Parent embedding remains available: a deployment-specific parent-origin policy has not been established. Any future `frame-ancestors` or `X-Frame-Options` decision needs a preview and published-hosting check. The production document receives the policy; the explicit local GraphQL explorer retains its separate development route.
The trusted build owns executable assets. This fitted policy establishes the named restrictions, rather than general safety of all same-origin code or future inputs. Ordinary startup computes it from the document it serves.
## Evidence and remaining receivers
Focused transport checks observe shared capacity across the actual GraphQL API factories, refusal before workspace storage, successful retry after completion, release after synchronous/asynchronous failure, and continued accounting after a response deadline. Existing GraphQL and deployment checks retain their registered-operation, streamed-body, response and ordinary-startup evidence. These observations use controlled handlers for concurrency; the follow-up requires no hosted database access or schema changes.
Earlier unit/browser observations cover bootstrap hashing, inserted-script/event blocking, failed-download reload and bounded cohort drafts. Source workspace journeys cover literal HTML/SQL/YAML-looking text and retained drafts/retries. [PostgreSQL proof](#document-docs-postgresql-md-a7cc27814ec8) and retained MySQL compatibility checks separately cover revision, retry, rollback, scope and expiry. [Local clone operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) records startup and recovery; a receiving host owns its deployment observation. [Disposable workspaces](#document-docs-visitor-workspaces-md-49294a63218a) provide bounded persistence, while verified private-data identity remains a separate future contract.
At the earlier request-admission delivery, `pnpm audit --prod --json` reported 252 production dependencies and zero advisories on 2026-11-17. That historical observation applies to that dependency graph. A current release follows [dependency maintenance](#document-docs-runbooks-dependency-maintenance-md-38672f828879) and refreshes its own advisory result; command, transport, browser and storage checks establish their separate behavior boundaries.
## Research decision
The reassessment compared keeping the existing request limits, adding generic query-cost/depth middleware, adding a client/IP rate limiter, and bounding concurrent application work. The fixed operation allowlist already controls query shape. A shared in-flight owner directly addresses the observed connection pressure with a small, dependency-free implementation. Client identity and trusted proxy attribution are not assumed; a verified-identity or hosting-scale change can reopen per-client/distributed rate limiting.
Official sources checked on 2026-11-17:
- [GraphQL security and demand control](https://graphql.org/learn/security/) distinguishes trusted documents, pagination, batching and runtime demand controls. This supports retaining the reviewed document set and adding a separate resource boundary.
- [OWASP GraphQL guidance](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html) joins input validation, authorization, timeouts and resource controls. The recommendation here applies those layers to the application's actual receivers.
- [Yoga persisted operations](https://the-guild.dev/graphql/yoga-server/docs/features/persisted-operations) documents explicit arbitrary-operation admission. Production retains the reviewed registry; the local explorer remains separate.
- [MDN 503 Service Unavailable](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/503) distinguishes temporary server overload from client-specific rate limiting and describes retry/caching considerations. The overload response follows that distinction.
- MDN's [CSP guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) and [script-source reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src) support exact script hashes and event listeners. Its [frame-ancestors reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors) distinguishes parent embedding from child-frame loading.
## `docs/research/permission-behavior.md`
Source document: `docs/research/permission-behavior.md`.
# Permission behavior and coherent exploration
The application makes each permission choice visible in the operation it governs. The shared typed policy evaluates the selected actor, requested action, canonical resource and environment to produce an explicit allow/refuse result. Controls preview that decision; accepted command owners evaluate it again before changing state.
This research supports the [workspace assessment](#document-docs-workspace-audit-md-c4b571428b60). The inspected application publishes synthetic examples. Browser persona selection demonstrates policy; private records require a separately designed verified server identity boundary.
## Findings and current response
**Supersession:** the original audit found a fixed first-principal gate, caller-only workflow checks, view-local grants and unrestricted public read projections. The delivered scenario, command and read owners replace those findings. [The scenario contract](#document-docs-permission-scenarios-md-cbea28e234a3) records current boundaries.
[Persona selection and scoped grants](#document-docs-permission-scenarios-md-cbea28e234a3) supply the acting context. Canonical command checks protect record and Plate effects; GraphQL reads and policy-partitioned histories use the same finite scenario. Source and workflow operations retain accepted results within their declared lifetimes, and Profile's appearance and optional-toast preferences reach their consumers. [Action delivery](#document-docs-research-action-delivery-md-cb14b0efa736) names each feature owner and its bounded effect.
A control's enabled appearance previews permission; the receiving command or API still evaluates its current inputs. [Reset scenario grants](#document-docs-permission-scenarios-md-cbea28e234a3) restores the example grants and clears the open grid draft while preserving unrelated accepted work and exploration. Verified identity remains a separate future contract.
## Options and synthesis
| Option | Useful contribution | Decision |
| --- | --- | --- |
| Wire the existing controls only | Immediate visible feedback | Bounded controls now delegate accepted effects to shared feature owners |
| Shared scenario, capability sets and command services | Coherent local behavior with inspectable rules | Delivered local foundation |
| Apply the same policy to GraphQL reads | Consistent lists, IDs, relationships and counts | Delivered through the [shared scope contract](#document-docs-permission-scenarios-md-cbea28e234a3) |
| Verified identity and durable policy administration | Authority for nonpublic records and multiple real users | Future explicit identity contract |
| SQL users or views as primary browser policy | Stable database projections and account privileges | Optional receiving need; the current shared account cannot identify a browser persona |
Use explicit capability sets for jobs, ordered rules for overlapping permission conditions, and existing transition tables for workflow legality. The current implementation uses typed capabilities and rules within the existing service owners. Audience perspective selects a reading focus; it remains independent of grants. A person's home region, a record's geography and the hosting region have distinct meanings.
## Receiving contracts
1. **Accepted commands, delivered.** Distinguish sample, order, clinical review, restore and query-repair capabilities. Resolve canonical resource metadata at the owner. Recheck the current scenario immediately before acceptance, including after a preview or confirmation. A refusal preserves records and timers. Shared-file identity remains separate from each result's consent.
2. **Read projection, delivered.** The shared policy filters receiving lists, counts, nested links and direct-ID returns; any future export must use the same projection. An authorized audit view can retain evidence explaining a consent hold while withholding the held operation. Grant editing evaluates the acting principal separately from the inspected principal.
3. **GraphQL context, delivered.** The server derives finite showcase personas and grants; client capability claims carry no authority. History cache identity includes policy scope, scope changes cancel obsolete requests, and refusal has its own result. A denied read must never fall back to the unrestricted catalog. A transport failure can still offer an explicitly allowed example projection.
4. **Visible actions, delivered.** Typed feature owners accept source, release-record, Map/QC, artifact and cohort operations; Profile settings connect to consumed presentation behavior. Each retained control performs a bounded local operation, offers a real next step, or states availability. Success copy names the accepted local effect. A showcase notification must not imply an external connector, clinical sign-off, cloud restore or durable audit event ran.
## SQL and deployment decision
Retain the current prepared base-table reads, request-owned connection and read-only transaction. For the retained MySQL adapter, `SQL SECURITY INVOKER` evaluates its database account. A shared runtime login cannot identify the selected browser persona. The same distinction applies to PostgreSQL view ownership and application scope. Views may later package explicit columns or support a restricted application account; they complement application policy.
A future view needs a concrete query consumer, confirmed hosted version and grants, explicit columns, ordinary-account `EXPLAIN` and result comparison, and a versioned setup/recovery path. Account-specific `DEFINER` clauses remain outside portable setup files. [Database setup](#document-docs-postgresql-md-a7cc27814ec8) and [deployment](#document-docs-deployment-md-7f6254f34e12) retain their explicit operator boundaries; a new view needs its own receiving use and migration evidence.
## Evidence and consequences
| Primary source | Local consequence |
| --- | --- |
| [GraphQL authorization](https://graphql.org/learn/authorization/) | Put authorization in a shared business/service layer; registered query shapes are a separate boundary from identity and resource access |
| [OWASP authorization guidance](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html) | Deny unsupported inputs, check resource scope and enforce at each effect; include direct command and direct-ID observations |
| [Yoga request context](https://the-guild.dev/graphql/yoga-server/docs/features/context) | Carry immutable derived policy alongside the request-owned repository |
| [Yoga response caching](https://the-guild.dev/graphql/yoga-server/docs/features/response-caching) | Partition viewer-dependent results; the current browser cache needs the same scope even without a server cache plugin |
| [MySQL view security](https://dev.mysql.com/doc/refman/8.4/en/create-view.html) | Treat SQL account authority separately from browser actor identity; verify the actual hosted version and privileges for any later view |
The initial source reading established the disconnected owners and allowed no-op paths. Focused executable cases and production-browser journeys establish the delivered commands, scoped reads and recovery paths. This research did not inspect private records, hosted grants or remote execution plans, and it makes no clinical-compliance claim.
## Language and Welcome
The [whole-view audit](#document-docs-workspace-audit-md-c4b571428b60) classifies language by its job. Supported actions lead operational guidance; future work occupies its own sentence. Exact consent, privacy, legal and access exclusions retain their meaning. Quotations and stored identifiers remain faithful. This improves inspectability for people; a future AI receiver needs its own representative behavior observations before claiming improved instruction reliability.
[Follow a sample](#document-docs-research-guided-exploration-md-ad62b036d202) now offers an optional first-arrival invitation, three question-led scenes, playback and manual takeover in the working Corridor and Plate views. Header replay remains available. AI-assisted presentation composition remains a separate design and acceptance decision.
## `docs/research/presentation-formats.md`
Source document: `docs/research/presentation-formats.md`.
# Presentation formats: evidence and decision
Visitors can review the same source-owned brief at three reading speeds: a message-led Briefing, a chapter-based Evidence review, and a continuous Report. The [presentation contract](#document-docs-presentation-styles-md-b2f82a4fd1a5) describes the resulting implementation.
## Evidence that changed the design
| Source and evidence class | Relevant finding or guidance | Receiving design decision and limit |
| --- | --- | --- |
| [Garner, Alley, Wolfe and Sawarynski, 2013; author research summary](https://writing.engr.psu.edu/research.html), controlled engineering-education study | Audiences heard the same explanation while viewing different slide structures. Message headlines supported by evidence improved measured understanding and retention relative to topic-and-bullet slides. | Briefing pairs one source headline with its supporting measures, sequence, comparison or explanation. This is a design inference for a showcase, not a measured comprehension gain in this application. |
| [Harvard Catalyst slide guidance](https://catalyst.harvard.edu/writing-communication-center/visualize-science/slides/), institutional communication practice | Strong headlines, relevant visual evidence, clear labels and restrained animation support the audience's reading task. | Units, qualifier notes and labels stay beside values; navigation reveals an entire source section. Existing material supplies the evidence; generated scientific figures are outside this change. |
| [Bringhurst, *The Elements of Typographic Style*, §§1.1–1.2](https://s3.amazonaws.com/arena-attachments/2584673/e36028a1643a616ec4be1e8d0e859fbb.pdf), typographic craft reference | Typography should express the text's structure; differentiated heading levels, related captions and incidental identity establish a coherent reading order. | Report uses quieter headings, adjacent explanatory content, a running deck identity and an approximately 78ch maximum reading column. That responsive measure is a local convention to verify in the browser, not a universal rule or a claim that the excerpt specifies screen dimensions. |
| [UNC Writing Center: Scientific Reports](https://writingcenter.unc.edu/tips-and-tools/scientific-reports/), academic writing guidance | Scientific report organization helps readers distinguish the work's purpose, methods, results and interpretation; conventions depend on the discipline. | Report keeps the sections actually present in each example. It does not fabricate missing methods, outcomes or IMRAD sections. |
| [Jambor et al., 2021](https://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.3001161), meta-research on image-based figures in 580 papers | Common interpretability gaps included missing scale information and incomplete explanations of colors, labels and depicted objects. | Every format carries source labels, units and qualifiers with its evidence. The paper studies published scientific images; this application-specific transfer remains a design inference. |
## Options and synthesis
A single recolored player preserved the old behavior but offered one reading pace. Separate independent templates could vary format substantially while creating several competing copies of the same content. An automatic summary mode would require an additional factuality and editing contract. A shared section model with explicit format selection gives visitors structural variation and keeps one source sequence.
The selected design retains the six existing visual identities as a separate choice from format. Briefing presents one section at a time; Evidence review keeps the expressive deck compositions with chapter navigation; Report gives the same material a continuous reading column and contents. Changing format preserves the current source section. Artifact composition uses the same path and supplies recorded artifact facts and acceptance checks.
## Evidence and future boundary
The unit observation checks source identity, section labels and the three navigation contracts. Production-browser journeys check two distinct deck identities, section continuity, the final reachable content, shared style overrides, artifact picks, desktop and compact laptop layouts, reduced motion and High contrast paint. These observations establish usable rendering and state transitions on the exercised paths; evaluating audience understanding would require a separate study.
The typed identity includes a stable source kind, and sections retain their source content object. A later generated-outline adapter can target that boundary when its own source/claim policy is approved. This delivery performs local projection of existing examples and records, with no AI calls. The [visual contract](#document-docs-presentation-styles-md-b2f82a4fd1a5) owns current composition and interaction details.
## `docs/runbooks/README.md`
Source document: `docs/runbooks/README.md`.
# Collaboration and delivery runbooks
Use the route that matches the receiving task. The [repository README](#document-readme-md-b33563055168) names current behavior and source owners; the active Issue or user instruction supplies scope and authority. A runbook orders already-authorized work.
| Route | Result | Standing |
| --- | --- | --- |
| [Focused change and independent review](#document-docs-runbooks-focused-change-md-dbaf4f5d73af) | One bounded change, fitting evidence and an independently reviewed handback | Working · v0.2.0 |
| [Select meaningful checks and deliver their result](#document-docs-runbooks-selective-check-delivery-md-0b5f34c348ca) | A discriminating test, proportionate suite and explicit executed/skipped result, with explicit artifact scope | Working · v0.1.0 |
| [Publication scan](#document-docs-runbooks-publication-scan-md-2fd2d22ef3bb) | A fresh-canary source/artifact observation, exact identity and private finding route | Working · v0.1.0 |
| [Public-visibility handoff](#document-docs-runbooks-public-visibility-handoff-md-778a29856725) | An owner-authorized visibility transition with contribution controls and signed-out receiving checks | Working · v0.1.0 |
| [Tagged documentation release](#document-docs-runbooks-tagged-documentation-release-md-33af7f4666be) | One reviewed static build, a verified artifact and explicit Pages activation | Exercised · v0.1.0 |
| [Dependency maintenance](#document-docs-runbooks-dependency-maintenance-md-38672f828879) | A justified dependency update with its receiving behavior and delivery checked | Working · v0.2.0 |
The working runbooks consolidate recurring repository practice; each awaits an end-to-end exercise as written. Independent reading exercises can expose useful corrections while leaving that full-route standing open. Record decision-changing findings in the existing PR or Issue, then update standing when the route has been exercised. Git retains prior versions; the current index supplies discovery.
[GitHub workflows](#source-87ee5504a3e2) provide Core as the normal code/configuration PR check and manual browser, compatibility-database and publication-scan choices. The [selection contract](#document-docs-development-automation-md-c3633dd085ca) explains run/skip, narrow smoke and combined Core/browser options. Their YAML owns triggers, permissions and retention; the runbooks explain when their results fit the task. A completed check supplies evidence, while the current grant and independent review govern delivery.
Database setup remains a separate operator action. [Local PostgreSQL operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) owns initialization, startup, backup/restore and confirmed reset. [Visitor workspaces](#document-docs-visitor-workspaces-md-49294a63218a) names the bounded Source storage receiver. Ordinary application startup serves accepted outputs and existing data.
The local [skill-authoring contract](#document-agents-skills-declarative-skill-authoring-skill-md-c0052dbaf783) and [writing guide](#document-agents-skills-declarative-skill-authoring-references-writing-and-evidence-md-b2b19351a072) support future instruction changes. Keep required methods and source links clone-local, name the actor and useful action, preserve exact boundaries, and distinguish authored examples from observed outcomes.
[Local PostgreSQL clone](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) supplies the isolated public-edition startup and recovery route, with per-clone storage and private credentials.
## `docs/runbooks/dependency-maintenance.md`
Source document: `docs/runbooks/dependency-maintenance.md`.
---
title: Dependency maintenance
version: 0.2.0
status: working
audience: [maintainers, coding-agents]
source_band: public_possible
task_type: collaboration_runbook
---
# Dependency maintenance
Update a named dependency family while preserving the visitor experience, mobile startup boundaries and ordinary Node/PostgreSQL delivery. Completion is an independently reviewed update whose manifest, lockfile and receiving checks agree.
## Establish the reason and receiving owner
Start with an active maintenance request, advisory or concrete compatibility need. Read [package.json](#source-7ae45ad102ea), [pnpm-lock.yaml](#source-32824c984905), the README's [dependency decisions](#document-readme-md-b33563055168) and the dependency's actual consumers. Confirm the branch, current commit and worktree; preserve unrelated edits through the [focused change route](#document-docs-runbooks-focused-change-md-dbaf4f5d73af).
Classify the dependency as browser runtime, server runtime, hosting build tool or development check. Follow the exact package/version's official release notes and advisory when selecting a target. Record the affected path and benefit; a registry advisory alone does not establish reachability in this application. An unavailable registry leaves the advisory observation unverified, while local source/lockfile inspection can continue.
## Update one coherent family
1. **Choose:** Keep related compatibility owners together. React and its types must agree; Vite's direct version and pnpm override must agree; Playwright and its installed browser revision must agree. Server-only GraphQL/MySQL machinery belongs outside the browser graph. A stack replacement needs its own receiving decision rather than being bundled into routine version maintenance.
2. **Change:** Use the repository's declared pnpm version to update the selected manifest entries and regenerate the lockfile. Inspect the resulting diff for unrelated upgrades, install hooks and newly introduced packages. Reinstall with `pnpm install --frozen-lockfile` to establish manifest/lockfile consistency. Preserve the reviewed package classifications while updating the selected family; the Docker build and native build each consume the frozen graph.
3. **Assess:** Run `pnpm audit --prod --json` for the locked production graph. When development tooling changes, also inspect `pnpm audit --json`. Keep raw diagnostic output local and summarize affected packages, severity, reachability and action in the PR. An audit finding earns a bounded repair, explicit remaining Issue or documented applicability decision; automatic force upgrades are not a substitute for that decision.
4. **Verify:** Follow the README's [complete local route](#document-readme-md-b33563055168), or manually select Browser checks with `run_checks=true`, `suite=all` and `include_core=true`. The combined Action installs and builds once before core and ordinary browser checks; `package_source=true` also prepares ordinary source when delivery is requested. For a Playwright update, use its matching Chromium revision; the default runner-Chrome `scene-smoke` route answers a narrower question. Add a focused receiving journey when the normal suite leaves a consequential behavior unobserved.
Use the existing startup check to detect Desktop or unopened Plate code entering the initial mobile bundle. Inspect a settled affected view when a rendering, animation, typography or UI dependency changes. Driver/schema changes select the [PostgreSQL proof](#document-docs-postgresql-md-a7cc27814ec8) and [clone proof](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) where their boundaries change. Retained MySQL compatibility uses `npm run test:mysql` or its manually selected isolated [workflow](#source-04bbbd5fdb96). That owner sequences engine checks and reseeding; the [workspace](#document-docs-workspace-storage-md-c97549ad8a50) and [catalog](#document-docs-persistent-data-md-115c93b26848) contracts retain the details. A routine dependency check never points those tests at the shared hosted database. Workflow/shared-setup updates earn a deliberate run of each affected route at the proposed revision; they no longer trigger all expensive jobs automatically. [Automation](#document-docs-development-automation-md-c3633dd085ca) owns run/skip choices and cache boundaries.
## Review, recover and deliver
Independent review compares the exact changed versions, source adaptations and evidence against the reason for the update. Keep major migrations and newly discovered larger gaps separately legible through meaningful Issue labels and milestones. If a candidate breaks receiving behavior, restore the prior manifest and lockfile together or retain the candidate on its branch while repairing the named incompatibility. Preserve unrelated work during either recovery.
The PR handback names the updated family, reason, direct/transitive scope, normalized advisory result with date, checks and their limits, plus any unresolved finding. Current authorization controls merge and release. Use [Node deployment](#document-docs-deployment-md-7f6254f34e12) for a requested release. Image/source identity and actual host behavior retain their respective observations.
These steps establish a bounded maintenance result. A later advisory, broken receiving behavior or changed hosting contract reopens the relevant owner rather than treating a prior clean audit as permanent assurance.
## `docs/runbooks/focused-change.md`
Source document: `docs/runbooks/focused-change.md`.
---
title: Focused change and independent review
version: 0.2.0
status: working
audience: [maintainers, coding-agents]
source_band: public_possible
task_type: collaboration_runbook
---
# Focused change and independent review
Deliver one useful, bounded change with evidence for its actual behavior and independent review of the exact receiving commit. Completion is the authorized PR handback or merge, with any remaining work routed explicitly.
## Enter from current truth
1. **Inspect:** Read the [README](#document-readme-md-b33563055168), the active Issue or user request, and the affected source and contracts. Confirm `git status --short`, `git branch --show-current` and `git rev-parse HEAD`. Establish the intended PR base from the current request. Preserve unrelated edits; use an isolated worktree when they overlap the task. If remote state is unavailable, identify that observation as unverified before publishing or merging.
2. **Bound:** Name the visitor behavior or source boundary being changed, the existing owner, and the observation that would distinguish success from a plausible failure. The request supplies edit, push and merge authority. A newly discovered larger gap can become a labeled, milestone-linked Issue while the current repair stays focused.
3. **Prepare:** Use the Node and pnpm versions declared in [package.json](#source-7ae45ad102ea) and install with `pnpm install --frozen-lockfile`. A tool, registry or environment failure leaves source work intact; resolve that prerequisite before claiming its checks passed.
## Implement and observe
Keep canonical state, current permission checks and accepted-command recovery with their existing owners. Read the README's source map before creating a second state store or bypassing a command. Update the nearest behavioral contract when its accepted behavior changes.
Choose the smallest fitting route from existing checks:
| Change | Observation and command shape | What it establishes |
| --- | --- | --- |
| Prose or runbook | Resolve relative links, compare instructions with current scripts, `git diff --check` | The document has an operable source route; runtime behavior is unchanged. |
| Pure command/state owner | `node --test tests/.test.mjs` | The named transition and refusal/recovery expectations hold. Add a focused test for a consequential missing case. |
| Visitor layout or interaction | `npm run typecheck`; `npm run build`; `npm run test:browser -- tests/browser/.spec.mjs` | The current build serves the affected interaction. Inspect a settled affected-view capture at the relevant phone/compact/desktop widths. |
| 3D scene or camera | The affected scene/gesture tests, `npm run check:3d`, and its browser journey | Geometry guards and direct manipulation/preset behavior retain their intended relationship. |
| GraphQL or server boundary | Build first, then the affected API/session/deployment tests | The registered operation and receiving transport agree with the built private data. |
| Shared dependency or release | The complete route in [Verify a change](#document-readme-md-b33563055168) | Type, geometry, current builds, unit/API and ordinary browser checks agree for the receiving source. |
Replace placeholder paths with files that exist in [tests](#source-59830ebc3a41). Tests that import `build/server` or inspect `dist` require `npm run build` after the relevant source change. Browser checks serve the production build, own port 3200 and refuse to reuse an unrelated server; coordinate the port or use a separate ignored configuration for concurrent work. Keep `.visual-runs` captures and traces local.
In Actions, Verify change receives every main PR with a fitting docs/Core route and full committed-tree scan. Select deeper checks when they can change the decision: Browser scene-smoke for core/responsive/guide behavior, Browser all with include_core=true for a shared dependency or release, and PostgreSQL proof for the engine/clone boundary. These selections preserve their own observed populations. Optional routes offer run_checks=false to skip allocation; Verify change always runs. [Automation](#document-docs-development-automation-md-c3633dd085ca) owns current controls and the inactive protection profile.
For animation-phase assertions, distinguish motion behavior from renderer throughput. The [desktop preset and Reset journeys](#source-303246a2d817) control browser time and read rendered transforms to observe intermediate motion, bounce, settlement and manual takeover. Real-time visual inspection still owns claims about perceived smoothness; a slow CI frame sample alone does not establish a changed spring curve.
For real MySQL proof, use `npm run test:mysql` with the disposable loopback database admitted by [scripts/prove-database.mjs](#source-a65b7b4c6772). That runner owns the destructive test order and reseeding between catalog, workspace and HTTP families. Keep connection settings local; the manually selected [database workflow](#source-04bbbd5fdb96) provides an isolated CI route. The [catalog](#document-docs-persistent-data-md-115c93b26848) and [workspace](#document-docs-workspace-storage-md-c97549ad8a50) contracts retain the schema and recovery detail. An ordinary suite's skipped database cases establish no engine or hosted result; report them separately and use the proof route when that boundary changes.
Build first and install the MySQL CLI. The runner receives `DB_*` through its environment, accepts only loopback and a database named `sot_*_test` or `sot_*_proof`, and owns its enable flags. For an explicitly prepared ignored local environment file, use `node --env-file=.env scripts/prove-database.mjs`. `MYSQL_CLIENT` can select an installed CLI. The runner leaves the example catalog and workspace tables initialized for separately requested stored-browser checks; it does not perform those browser journeys itself.
## Review, recover and return
- **Review:** Ask an independent reviewer to inspect the exact commit, relevant source and fitting evidence. Give them the behavior, changed owners and any remaining uncertainty. Their return is actionable findings or approval at that commit. Repair findings, rerun affected checks and renew review for material changes.
- **Recover:** When a check fails, distinguish source failure from unavailable prerequisites. Preserve edits and drafts while resolving the smallest owned cause. A failing consequential check, unresolved review finding or missing publication authority stops the corresponding delivery step; return the concrete blocker and next action.
- **Deliver:** Use one PR as the public-safe receiving record: problem and resulting behavior, scope, normalized check results and coverage, review, recovery and any next Issue. Apply meaningful labels and a milestone. Merge only within the current grant and after required review/checks; the runbook supplies no additional authority.
- **Hand back:** State the changed surface, exact PR/commit and `pass`, `friction` or `blocker`, with one next receiver when work remains. Keep credentials, private logs, browser state and protected hosting coordinates with their authorized owner. Use [Node deployment](#document-docs-deployment-md-7f6254f34e12) and [local clone operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) for an application delivery or recovery request.
## `docs/runbooks/local-postgresql-clone.md`
Source document: `docs/runbooks/local-postgresql-clone.md`.
# Run and recover a local PostgreSQL clone
This route gives one checkout its own PostgreSQL volume and Node application. It stores the canonical synthetic Plate catalog and expiring Source metadata edits. Other workflow edits retain their current browser-session lifetime. The database serves examples for exploration; clinical operation and identity verification remain separate adaptations.
## Start one clone
Install Docker with Compose v2 or newer, Git, and Node 22.15+ within 22.x. Docker Desktop, a separately owned Colima context, or another compatible Linux engine can supply the daemon. The image build installs the repository’s pinned pnpm and frozen dependencies; host pnpm is useful for source development but unnecessary for these commands.
```sh
node scripts/clone.mjs configure --port 3000
node scripts/clone.mjs up
```
Open `http://localhost:3000`. Configuration creates a random Compose project identity, independent owner/runtime passwords and a checksum tying `.env.clone` to this checkout’s real path. The file is private and ignored. Keep it with the volume; copying a checkout to a new location calls for a new configuration. Two directories with the same basename receive different projects and volumes. Select another port during configuration when another clone is already running.
The PostgreSQL service has no published host port. The app publishes only `127.0.0.1:`. The database image bootstraps ordinary `sot_owner` and `sot_runtime` roles once for a fresh volume. Compose then waits for database health and a successful one-shot initializer before starting the app. That initializer uses the accepted catalog/workspace migration owners and grants the runtime only catalog reads and required workspace operations. Ordinary app startup preserves stored rows.
`compose.yml` and `Dockerfile` own exact image digests: PostgreSQL 18.7 and Node 22.23.5 for supported Linux architectures. The local acceptance observation names its tested architecture; other receiving platforms earn their own execution check. Update image versions/digests through a focused dependency change, then exercise fresh setup and recovery before adopting them. A database major-version upgrade needs its own explicit migration/restore plan.
To choose an existing Docker context without changing the global default:
```sh
SOT_DOCKER_CONTEXT=your-context node scripts/clone.mjs up
```
This is an optional context name, not a prerequisite to create a VM. The recipe sends build context and keeps database data in a Docker volume; it uses no host-source bind mounts.
## Observe real persistence
Open Plate → Sample history and select C3. The history source should show **Stored history**. In Sources, start a saved workspace and change a title. Reload, then stop/start this clone and verify the accepted title remains:
```sh
node scripts/clone.mjs stop
node scripts/clone.mjs up
```
Stop preserves the volume and local configuration. Source workspace access remains tied to the original browser cookie, exact origin including port, and 24-hour expiry. A new browser or changed port is a different receiving context; restoring database rows does not issue a new workspace credential. The canonical Plate catalog remains available without an active Source workspace. Browser cookies are scoped to the host, while the workspace also checks the exact origin. Use separate browser profiles or isolated contexts when exploring two clones on different localhost ports at the same time, so their cookies stay separate.
## Inspect and recover
```sh
node scripts/clone.mjs status
node scripts/clone.mjs logs
```
Status names this clone’s containers. Logs show a bounded app/initializer tail. If initialization refuses an unowned, partial, newer or drifted schema, keep the volume and inspect the accepted migration contract before retrying. Repeating `up` runs compatibility checks and retains complete records. A failed startup is an observable failure, not a request to silently substitute bundled data.
Database health establishes a reachable server. Initializer success establishes accepted schema/seed compatibility. The app’s HTTP healthcheck establishes an answering page; the Stored-history and accepted-edit observations above establish useful storage behavior.
## Back up and restore this clone
```sh
node scripts/clone.mjs backup
```
Backup writes a private custom-format PostgreSQL dump under `.clone/backups/`. Dumps can contain workspace verifiers and accepted metadata; keep them local or in access-controlled storage. The recipe excludes them, local environments and caches from image build context. It records table data without role credentials, ownership reassignment or grants.
Restore only a trusted backup from this application/schema version. The command first stops the app, restores in one database transaction, reruns schema validation/runtime grants, then starts the app. It replaces this clone’s stored rows. Use the exact project name reported by configure/status as confirmation:
```sh
node scripts/clone.mjs restore .clone/backups/.dump --confirm
```
A failed restore or compatibility check keeps the app stopped and the private backup available. Fix the reported local condition before restarting. Retained Source access requires the original cookie/origin within its original expiry; an expired workspace correctly remains expired after restoration. App rollback and database restoration are distinct actions: use an application revision compatible with the stored schema.
## Reset one clone deliberately
First save a backup if its edits matter. This command removes only the explicitly confirmed project’s containers and volume; it retains configuration and backups:
```sh
node scripts/clone.mjs reset --confirm
node scripts/clone.mjs up
```
The next startup creates fresh examples. Another clone’s project/volume is outside this operation. Old browser workspace credentials will no longer resolve; start a new Source workspace through its ordinary control.
## Use an existing native PostgreSQL server
The same application can use an operator-owned PostgreSQL 18 database. Provision a dedicated database, an ordinary schema-owning login, and a separate runtime login first. The runtime needs database CONNECT and public-schema USAGE; give the setup role CREATE in its owned public schema. Keep cluster superuser credentials outside the application. Choose distinct database and role names when multiple clones share one server.
Install locked dependencies and run `npm run build`. In a private ignored environment file, set `DATABASE_PROVIDER=postgres`, `PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER` (setup owner), `PGPASSWORD`, and `SOT_RUNTIME_ROLE` (the already provisioned runtime login). For a controlled loopback server set `PGSSLMODE=disable`; remote adapters use verified TLS and their own deployment review.
```sh
node --env-file=.env.local-postgres scripts/clone/initialize.mjs
```
The initializer invokes the same canonical migration/seed owners and grants only the required table privileges to the named runtime. Then use a separate private environment file carrying the runtime login/password to serve:
```sh
node --env-file=.env.local-runtime scripts/serve.mjs
```
`PORT` chooses the app port. The ordinary Node server binds all interfaces, so use the host’s local firewall or an appropriately restricted listener/reverse proxy for a private native installation. The Compose route above supplies the loopback publishing boundary directly. Native `pg_dump`/`pg_restore`, service restart and database-role administration belong to that operator; the clone CLI intentionally targets only its own Compose project.
## Run the owned clone proof
`node --test tests/clone.test.mjs` checks configuration identity, privacy, command selection and the runtime-role preflight without Docker. The optional integrated proof creates two temporary same-named checkouts and random Compose projects in an explicitly selected context:
```sh
CLONE_COMPOSE_TEST=1 SOT_DOCKER_CONTEXT=your-context node --test tests/clone-compose.mjs
```
It copies the current Git-tracked and nonignored working source, applies the receiving overlay to the second copy when that manifest is present, and observes Stored history, independent Source edits, container restart, failed and successful backup restoration, reset isolation and offline recovery. It owns loopback ports 33305 and 33306 by default; `CLONE_APP_PORT` and `CLONE_PEER_PORT` select alternatives. Each project's containers and data volume are removed afterward. A failure retains private local configuration/logs for its recovery receiver; it selects no unrelated projects. This API proof retains distinct synthetic cookies per origin. A browser projection check remains a separate observation.
## Source and evidence
[Docker Compose startup order](https://docs.docker.com/compose/how-tos/startup-order/) distinguishes health from successful one-shot initialization. The [official PostgreSQL image](https://hub.docker.com/_/postgres) documents fresh-volume init behavior and PostgreSQL 18’s volume layout. [Database choices](#document-docs-database-choices-md-a44edbfece29), [visitor workspaces](#document-docs-visitor-workspaces-md-49294a63218a) and [server owners](#source-93e4a5263a59) explain the surrounding boundaries.
This runbook accompanies a clone recipe. Record the actual fresh/restart/restore/two-clone observations with the receiving PR; its commands alone establish no hosted deployment or clinical suitability.
## Select the CI receiver
The manual [PostgreSQL clone proof](#source-8ab7cc430f4a) runs the same `tests/clone-compose.mjs` journey on the runner-owned Docker context. Select the reviewed branch or tag and leave `run_checks=true`; clearing it skips the job before runner allocation. The test creates two temporary projects and cleans up only those identities. Credentials, backups, cookies and diagnostic logs stay on the ephemeral runner. The workflow publishes no application or database artifact. A successful run establishes its local container/recovery behavior; a remote deployment retains its own receiving check.
## `docs/runbooks/public-visibility-handoff.md`
Source document: `docs/runbooks/public-visibility-handoff.md`.
---
title: Public-visibility handoff
version: 0.1.0
status: working
audience: repository owner and authorized assisting maintainers
source_band: public_possible
task_type: operational_runbook
---
# Open the repository with reviewed contribution controls
Use this route when the owner explicitly authorizes making the named repository public. Preparation, passing checks and this document supply a reviewable handoff; they leave visibility unchanged. After an authorized transition, the receiving Issue or PR records the actual public state. A future collaborator can use that record to distinguish completed work from this reusable procedure.
## Prepare while access is restricted
Confirm the exact repository, accepted `main` and `docs` revisions, release tags and proposed visibility. Retain recovery coordinates and current Pages/Actions settings with the owner. Public forks can remain public after a later visibility reversal, so recovery focuses on correcting exposed material and restoring controls rather than recalling copies. [GitHub visibility effects](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility)
Use the [publication scan](#document-docs-runbooks-publication-scan-md-2fd2d22ef3bb) for the accepted source, available history and named generated artifacts. Review native images and file metadata separately. Include the GitHub material that will become accessible: Issues, PR discussions, releases, workflow histories, logs and retained artifacts. Inspect linked private locators and rights as well as credentials. A clean textual-history scan establishes its declared scope; historical binary files and unfetched refs need their own observation. GitHub makes Actions history and logs public with the repository. Keep raw findings private and resolve material exposure before the transition.
Record effective settings against the [protection contracts](#source-f32a9eda0632):
- `main` and `docs` require PRs, resolved conversations and strict current checks, with no bypass. Zero required approving-review badges supports the solo owner; independent technical review remains recorded.
- Release tags allow administrator creation and retain separate update/deletion prohibitions without bypass. Pages deployment admits `main` only.
- Actions uses read-only default tokens, cannot approve PR reviews, requires full-SHA action references, and preserves the accepted allowed-action policy. Private-fork execution, write-token and secret forwarding stay disabled. Private action/workflow sharing remains closed.
- Confirm the repository and environment secret/variable inventories, collaborators and installed integrations. Keep the current minimal authority unless a separate task requires more. Confirm Dependabot alerts; automatic security/version-update PRs are separate choices.
Check settings from the account, not just template JSON. The [Actions settings guide](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) and [Dependabot alert guide](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configure-dependabot-alerts) describe those controls.
## Carry out the approved transition
The approved public policy is `first_time_contributors_new_to_github`, GitHub's least restrictive option. It retains the platform's approval requirement only for contributors who are both new to GitHub and without a merged contribution to this repository. The repository adds no blanket external-contributor approval gate. The [permissions API](https://docs.github.com/en/rest/actions/permissions) defines the supported values and readback operations.
The readiness inspection found that GitHub refused a read of this repository's public-fork policy endpoint while it was private. Apply and read back the chosen minimum immediately after visibility changes. A short Actions pause can cover that transition interval when the owner chooses this sequence:
1. Hold merges and new release dispatches. Let owned active runs finish, or cancel them deliberately; confirm that no deployment remains in progress. Save the effective Actions policy so re-enabling preserves it.
2. Disable repository Actions and verify the result. This pauses verification and deployment workflows; plan the handoff when that interruption is acceptable.
3. The owner changes the confirmed repository's visibility to public.
4. Set and read back `first_time_contributors_new_to_github`. Recheck the settings above, including effective branch/tag protection, main-only Pages, SHA enforcement and token limits. Account capabilities can change with visibility; preserve each intended boundary through its actual supported setting.
5. Re-enable Actions with the saved allowed-action policy only after the required readbacks succeed. Keep merges held until the receiving checks below finish. If a boundary remains unconfirmed, leave Actions paused and return the precise setting and recovery action to the owner.
Review the exact candidate before merge, including workflow/action changes and code executed by package installation, builds and tests. When GitHub requests run approval under its minimum policy, perform that inspection before approving execution. A green check name supplements this review; it does not replace it. The [fork-run review procedure](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/approve-runs-from-forks) explains that occasional platform step; execution approval and merge acceptance remain separate decisions.
## Observe the public receiving experience
From a signed-out browser, open the repository, README images, source links and support/security routes; make a fresh unauthenticated clone. Confirm the available private vulnerability-reporting route against [SECURITY.md](#document-security-md-f6ed156e4bf5), retaining its safe contact-request fallback where needed.
Confirm that an owned, non-publishing PR receives the actual required check and merge restriction. Exercise one bounded selected-check failure, repair it, and observe the successful result at the repaired revision. Preserve the separate trusted docs-branch check. Use [selective checks](#document-docs-runbooks-selective-check-delivery-md-0b5f34c348ca) rather than adding unrelated browser or database work to a visibility change.
Check the live application and Pages domain over HTTPS, including a direct documentation route and its assets. Repository visibility publishes source access; it does not rebuild either hosted surface. Deliver changed standalone articles through the [tagged documentation release](#document-docs-runbooks-tagged-documentation-release-md-33af7f4666be). The application's `/docs/` remains part of its own Node build and deployment, so it receives those changes through a separate application release.
Close the handoff in one Issue or PR with accepted revisions, current visibility, settings readbacks, executed checks and their limits. Link existing sanitized evidence instead of duplicating logs. Real-user identity, private scientific records and broader product work retain their existing design boundaries. The owner then releases the merge hold; future contributors follow [CONTRIBUTING](#document-contributing-md-eca12c0a30e2).
## `docs/runbooks/publication-scan.md`
Source document: `docs/runbooks/publication-scan.md`.
---
title: Publication scan
version: 0.1.0
status: working
audience: solo repository owner and assisting agents
source_band: public_possible
task_type: operational_runbook
---
# Inspect a publication candidate
A receiving snapshot or release carries a verified source identity, a fresh-canary detector result and a clear account of what was inspected. This route preserves the current application and its Node/PostgreSQL delivery paths. The owner separately decides publication, repository visibility, credential rotation and any history repair.
## Enter with current source
Confirm branch, working changes and the intended commit. Preserve unrelated changes. Use Node 22.15+ within 22.x, Git, and the repository's ordinary build tools when inspecting generated output. A shallow clone can inspect its source; history mode waits for the owner-authorized ref acquisition. An unavailable binary or source selection returns an incomplete observation rather than a clean receipt.
The [installer](#source-c19fa97b0565) pins BetterLeaks **1.10.1** and official platform checksums. Install once into ignored `.tools/`; later scans work offline. The only scanner network step is this explicit download. Candidate validation and revocation remain disabled.
```sh
npm run test:security
npm run security:install
npm run test:security:engine
```
`test:security` exercises the wrapper, installer and ZIP boundaries without network or an installed engine. The separate engine check requires the verified binary; it proves a fresh canary and that exact fixture exceptions still detect the same value elsewhere and a changed value in an allowed file. Ordinary `npm test` excludes this preparation and engine work.
## Select one observation
Every `security:scan` invocation verifies the installation and generates a fresh non-issued canary before its chosen scope.
| Command | Material inspected and useful boundary |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run security:scan -- canary` | Detector liveness, finding exit, parser and masking; source remains unobserved. |
| `npm run security:scan -- tree` | Current bytes of Git-tracked working files. Untracked/ignored files require an explicit artifact selection. Missing, symlinked or special tracked entries stop the scan. |
| `npm run security:scan -- index` | Every stage-zero index blob, including unchanged and skip-worktree entries. Unstaged bytes do not replace the proposed commit. Conflicts and submodules stop the scan. |
| `npm run security:scan -- export HEAD` | Complete selected committed source, materialized from raw Git blobs without checkout filters. A clean export does not inspect earlier history. |
| `npm run security:scan -- changed BASE_COMMIT` | Added/changed committed files between the available base and `HEAD`. This is the ready-PR path; unchanged files and removed historical content remain with deeper scopes. |
| `npm run security:scan -- history` | Full-history textual patches across locally available refs, including separate merge diffs. Requires a non-shallow clone; unfetched refs, dangling objects, GitHub prose and binary bytes absent from patches remain outside it. |
| `npm run security:scan -- artifact dist` | One contained generated directory, including ignored files. Symlinks and hidden scanner-ignore files stop the scan. |
| `npm run security:scan -- artifact .deploy/release.zip` | Contents of one contained ordinary ZIP, safely materialized before scanning. This path is an example; select the actual reviewed archive. |
Materialized source and artifact receipts include a deterministic file-content identity. A ZIP additionally reports its archive digest. The parser accepts ordinary stored/deflated, single-disk ZIPs up to 100 MB, 256 MB expanded and 10,000 entries. Directory inputs are copied into an owned temporary snapshot before hashing and scanning; ZIP identities come from the same bytes that are extracted. It rejects encryption, ZIP64, unsafe paths, duplicate/colliding entries, symlinks and failed CRC/size checks. Nested archives receive no recursive expansion; name each required archive explicitly. Generic archive forensics remains outside this source-delivery route.
## Inspect a complete release
Use the reviewed revision and normal build owners. Build artifacts are generated from the working source, so confirm it equals the reviewed commit before reporting source-to-build identity.
```sh
npm run security:scan -- export HEAD
npm run build
npm run security:scan -- artifact dist
npm run security:scan -- artifact build
```
If a separate release archive will be delivered, select its exact path with `security:scan -- artifact`. Its producer owns membership, size and source identity; the scanner establishes only its declared detector result. The built-release workflow checks committed export plus `dist` and `build`. A receiving repository repeats applicable checks after assembling its source.
## Receive a result or recover
A clean receipt records the engine version, configuration digest, fresh-canary result, selected scope and safe source/artifact identity. Return that small result in the existing PR or Issue. Raw scanner reports and diagnostics remain transient in process memory; the wrapper prints no finding paths, candidate values or commit messages. Preserve the complete error as private context only when a protected receiver needs it.
A finding stops the affected handoff. The solo owner or authorized agent inspects the named source locally and determines whether it is a real credential, runtime indirection or non-issued fixture. A plausible credential goes to its provider owner for revocation/rotation before cleanup. Any history rewrite requires its own authorization. Exact synthetic exceptions live only in [`.betterleaks.toml`](#source-5c695e582d60), with scope/rationale and a discriminating engine check; rerun the canary and affected scopes after changing one. Hidden ignore files, inline allowances and finding-count baselines do not participate.
The current exceptions cover disposable loopback CI credentials and two mocked unit fixtures. They authorize no hosted access. A changed value, path or rule remains observable. The detector's configuration and dependency defaults are version-bound; an upgrade reviews checksums, CLI/report behavior, canary, fixtures and real scopes together.
## CI and public carriers
[Publication scan](#source-6cf50cec3027) provides manual source, history and built-artifact selection. Verify change owns the complete committed-tree scan on every main PR. Clearing the optional scan's run_checks skips before allocation. Source scopes prepare Node and the scanner; release scope also builds the accepted source. Checks return normalized identity/results, while raw reports, caches and artifacts stay with their diagnostic owners.
Before a public handoff, inspect embedded image/archive metadata separately: location, device identity, authorship, timestamps and packaged paths. Preserve intentional color/profile/attribution fields. Review visible content, rights and intended audience with the owner. The generated `llms` documentation is another publication carrier and receives the build-artifact scan. Its source selection remains with the documentation generator and publication manifest owner.
Complete this route when every requested scope is clean or has a named private recovery owner, metadata/audience decisions are explicit, and the receiving record names the next action. A clean scan establishes no universal absence of secrets, provider validity or permission to publish.
References: [BetterLeaks stable release](https://github.com/betterleaks/betterleaks/releases/tag/v1.10.1), [GitHub secret-scanning scope](https://docs.github.com/en/code-security/reference/secret-security/secret-scanning-scope).
## `docs/runbooks/selective-check-delivery.md`
Source document: `docs/runbooks/selective-check-delivery.md`.
---
title: Select meaningful checks and deliver their result
version: 0.1.0
status: working
audience: [maintainers, coding-agents]
source_band: public_possible
task_type: collaboration_runbook
---
# Select meaningful checks and deliver their result
Give an independently reviewing collaborator a useful result for a bounded change without repeating unaffected work. This route completes when the selected checks, actual execution standing, coverage and next receiver are clear in the existing PR or Issue. A built artifact retains its exact source identity; hosted publication has its own receiving observation.
This is a working runbook until a fresh reader completes its route. [The testing skill](#document-agents-skills-test-suite-composition-skill-md-412c39ca5e33) owns test design and selection reasoning; [automation](#document-docs-development-automation-md-c3633dd085ca) owns current workflow controls; [focused change](#document-docs-runbooks-focused-change-md-dbaf4f5d73af) owns the broader implementation/review cycle.
## Enter with a bounded change
- **Source:** Read the current request, relevant Issue, [README](#document-readme-md-b33563055168), changed owners and existing tests. Confirm `git status --short`, `git branch --show-current` and `git rev-parse HEAD`. Preserve unrelated edits. If the revision or remote state is uncertain, establish it before publishing a result tied to that source.
- **Authority:** The request supplies permission to change tests, run commands, dispatch CI, package or merge. This runbook supplies order. Where an action is outside the grant, prepare its concrete result and hand it to the authorized owner.
- **Behavior:** Name the intended consequence and one plausible fault. If product meaning remains unsettled, return that decision to its owner while source inventory continues.
- **Environment:** Read the declared toolchain and runner prerequisites. An unavailable prerequisite leaves its observation incomplete; use the preparation or manual CI route rather than silently reducing the claim.
## 1. Select the observation — inspect and plan
Use the existing [source/command map](#document-agents-skills-test-suite-composition-references-source-and-command-map-md-f30f1f46ce54). Choose a pure-owner test for a transition, API/adapter test for a transport boundary, browser journey for an interaction or remount, and disposable SQL proof for engine behavior. A prose-only edit usually needs local link/source review and `git diff --check`.
State the selected files/cases and what would expand the route. A shared dependency, cross-family state owner or release candidate usually reopens the complete ordinary route. A schema/driver/transaction change adds the database receiver. Hosted acceptance remains a later operator observation.
**Checkpoint:** The plan connects each selected check to a changed owner and intended consequence. If no existing assertion distinguishes the plausible fault, add a focused case using an independent fixture or invariant. Keep its setup/cleanup with existing owners. [Test design and recovery](#document-agents-skills-test-suite-composition-references-test-design-and-recovery-md-c721a76a4631) supplies concrete examples.
## 2. Prepare the chosen route — local execution or explicit dispatch
For local work, install the declared dependency graph with `pnpm install --frozen-lockfile`. Run the selected pure test directly. Build with `npm run build` before cases that inspect `dist`, import private server output or launch the production browser server. Install the matching browser when needed; keep port 3200 available or coordinate an ignored alternate configuration with an explicit repository-root working directory.
For GitHub Actions, verify the selected branch/tag and use these controls:
| Need | Deliberate selection | Result |
| --- | --- | --- |
| Main PR | Verify change always runs, including drafts, and selects docs or Core plus full committed-tree scanning. | Required selected observations at the proposed merge revision. Optional Core remains manually available. |
| Quick Corridor/Plate/guide receiving check | Browser `suite=scene-smoke` | Named smoke files on runner Chrome, with version recorded; locked Chromium fallback if unavailable. |
| Broad interaction/dependency proof | Browser `suite=all`, `include_core=true` | Complete ordinary browser population plus Core, sharing one installation/build in the job. |
| PostgreSQL engine/transaction or clone proof | [Native engine populations](#document-docs-postgresql-md-a7cc27814ec8) or manual [PostgreSQL clone proof](#source-8ab7cc430f4a) | Explicit disposable ownership, initialization and recovery evidence. |
| Retained MySQL compatibility | Optional MySQL compatibility proof | Isolated service and owned destructive sequence; shared databases remain untouched. |
| Intentionally rest a manual route | `run_checks=false` | Whole job skipped before runner/services; no behavior or artifact result. |
Optional dispatches default `run_checks=true`; Verify change always runs. Browser smoke and full-suite results retain their different populations. SQL proof stays separately selected. The inactive main profile names the unfiltered Verify change job; docs protection has a separately pinned data-only check. See [automation](#document-docs-development-automation-md-c3633dd085ca) for exact trigger and concurrency rules.
**Checkpoint:** Preparation matches the checked source and selected population. An existing package cache still receives frozen install verification. Separate jobs share setup code/cache, not a VM or accepted build/test result. Reuse within the Browser job retains one source and environment identity.
## 3. Execute and interpret — observe
Run the selected command. For uncertain browser membership, use Playwright's `--list` route first; discovery leaves behavior for execution. Inspect the case names and skips as well as exit status. A controlled async race should finish through its expected owner, not an arbitrary sleep. A visual change earns a settled affected-view inspection at its meaningful viewport; test success alone leaves visual quality open.
For PostgreSQL, select the explicit [native proof populations](#document-docs-postgresql-md-a7cc27814ec8) against independently owned disposable databases, or use the [Compose proof](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277). MySQL compatibility uses `npm run test:mysql` with disposable loopback `DB_*`, MySQL CLI and a current build. Its runner owns destructive ordering and reseeding. Keep shared or hosted databases outside those routes, including tunnels that make a remote endpoint appear local.
**Checkpoint:** Record which selected observations executed and which remain incomplete. A required case that skips for missing configuration needs its prerequisite or a named next receiver. Stop a claimed release handback when consequential assertions or required observations remain unresolved.
## 4. Recover proportionately — repair the responsible owner
| Condition | Safe next action |
| --- | --- |
| Missing dependency, browser, build or free port | Preserve source work, restore the named prerequisite and repeat the same focused route. |
| Assertion disagrees with the current accepted contract | Inspect the fixture and implementation; repair the supported owner and keep the original failure meaningful. |
| Later source changes affect an earlier build/result | Rebuild and rerun affected consumers; retain unrelated evidence with its original revision and scope. |
| Interrupted browser/server fixture | Confirm owned handles and child processes were released before reusing the port or temporary directory. |
| SQL proof fails midway | Keep its database disposable and rerun through the guarded runner after repair; its ordering owns reset and initialization. |
| Registry/cache/runner service is unavailable | Use the direct preparation route when available, or report an incomplete prerequisite with the next receiving owner. |
Broaden testing when the failure reveals a shared cause or new dependency edge. Avoid treating repetition alone as assurance: a passing rerun leaves an unexplained intermittent fault open. Compare setup/build/test phases before changing suite size or adding caching infrastructure.
## 5. Receive review and hand back — review and deliver
Ask an independent reviewer to inspect the exact intended commit, changed owners and selected evidence. Provide the plausible fault and coverage boundary so the reviewer can assess whether the observation is useful. Repair material findings and renew affected evidence/review. Current authorization governs merge.
Use one concise PR/Issue result: changed behavior; exact source and command/population; executed pass, failure, skipped or incomplete standing; what it establishes; relevant environment; and the next action if one remains. Raw diagnostics, cookies, browser state and hosting coordinates stay with their protected owner. Test counts can describe population but cannot replace its meaning.
If an artifact is requested, record its digest and reviewed source revision. Follow [Node deployment](#document-docs-deployment-md-7f6254f34e12) or [local clone operations](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) for the receiving environment. Preserve a prior reviewed application artifact and its separate database recovery route. Hosted observation completes deployment acceptance independently of local tests.
The route is complete when the reviewer can distinguish checked behavior from held work and can resume the next step without reconstructing the conversation. A fresh-reader exercise can promote this runbook's status; a workflow, source-owner or receiving-contract change reopens the relevant section.
## `docs/runbooks/tagged-documentation-release.md`
Source document: `docs/runbooks/tagged-documentation-release.md`.
---
title: Release a reviewed documentation build
version: 0.1.0
status: exercised
audience: repository owner and authorized maintainers
task_type: operational_runbook
---
# Release the documentation independently
Publish the reviewed static documentation at `https://kindlight.foundation` while the application continues at `https://kindlight.ai`. The application's `/docs/` projection keeps its own build and delivery path. This route changes the Pages artifact; repository visibility remains a separate owner decision.
## Enter with accepted source
Use the protected `main` and `docs` branches and their active review checks. `main` owns the application, documentation generator and trusted release tools. `docs` owns reviewed publication data and its immutable `docs-vMAJOR.MINOR.PATCH` tags. The Pages source is **GitHub Actions**, and the `github-pages` environment admits deployments from `main` only. The repository owner confirms these settings before activation.
The initial `site-release.json` on `docs` contains:
```json
{
"version": 1,
"appRevision": "",
"origin": "https://kindlight.foundation",
"base": "/",
"media": []
}
```
The publication commit also retains the approved `CNAME` and exact `LICENSE`. This first release uses the documentation generator's existing assets; a nonempty media list needs a reviewed extension of its path, attribution and rendering contract. The config contains data, and the release tools never execute files from `docs`.
Merge the config through its ordinary reviewed docs PR, then create its immutable documentation tag under the repository's tag authority. `appRevision` binds that tag to one accepted app source. App tags remain independent. A later app revision receives a new config commit and documentation tag. Tag protection preserves accepted references; an unsuccessful preflight leaves a tag as an identifiable source selection, rather than proof of a deployed site.
## Build once and receive the artifact
Run **Documentation preflight** from `main`, supplying the full app commit, full docs commit and its documentation tag. The action validates all three commit identities, accepted ancestry and config/tag agreement before dependency installation. It builds the foundation profile once using the selected app's locked toolchain. The trusted workflow and validators come from the dispatch's accepted `main` revision, which may be newer than the selected app revision.
Preflight checks generated article routes, ordinary local HTML links and assets, canonical origin, the isolated documentation module graph, ordinary file paths and the complete artifact's fresh-canary publication scan. Its normalized summary names:
- App, publication and preflight workflow revisions.
- Documentation tag, run ID and attempt.
- Sorted file-manifest SHA-256, file count and total bytes.
The immutable artifact retains `site/`, `manifest.json` and `receipt.json` for **14 days**. Inspect the generated pages from that artifact before activation, including a direct article, an internal link, appearance controls and one narrow viewport. Preserve intentional attribution and review any new media metadata under the [publication scan runbook](#document-docs-runbooks-publication-scan-md-2fd2d22ef3bb). The automated link check covers quoted HTML destinations and file presence; visual quality, external destinations and fragment behavior remain receiving observations.
This workflow has read-only repository permissions. It neither deploys nor creates tags. A successful run proves its named source and artifact checks; a local build or failed run supplies no deployment receipt.
## Activate those same files
Run **Activate documentation** from `main` with the successful preflight run ID, the reviewed file-manifest digest and documentation tag. Select **activate_deployment** only for the owner-authorized publication. Its default `false` skips allocation and deployment.
Activation accepts a successful manual preflight from this repository's protected main workflow, selects the artifact for that exact run attempt, and verifies its ID, receipt, accepted source ancestry, immutable tag and every file hash. It scans the receiving artifact, then transfers the same static files into the current run's Pages artifact. It performs **no rebuild**. A fresh preflight is the recovery route for an expired artifact; receive its new digest before activation.
Only the final deployment job holds `pages: write` and `id-token: write` in the `github-pages` environment. That job runs the pinned GitHub Pages deployment action. The preceding verification job has read-only repository and Actions access. Every third-party action is pinned to a full commit. Main-only dispatch guards reject a mistakenly selected branch; environment restrictions supply the second deployment boundary.
After deployment, open the foundation site signed out. Check the home page, direct article refresh, asset loading, a narrow viewport, appearance controls, a missing route, HTTPS and the canonical domain. Confirm the application link still reaches `kindlight.ai`. A private source repository continues to require an invitation even when its Pages documentation is publicly readable; retain the documentation's access note until the owner changes that visibility deliberately.
## Recover and hand back
Keep the currently served site while a candidate fails. Correct the owning source through review and create a new publication commit/tag when the selected source changes. For a prior accepted release, activate its retained verified artifact and digest, or rerun preflight for the same immutable app/docs pair and receive the newly built artifact. A rebuild is a new artifact observation even when its source coordinates match. Release artifacts use ordinary Pages storage and retention; they are not a permanent backup service.
Complete the return in the existing release PR or Issue: selected tag and three revisions, preflight and activation runs, manifest digest, normalized checks, signed-out host result, and any remaining host or visibility action. Keep raw logs, credentials and account details with their protected owners. The first end-to-end exercise published `docs-v0.1.0` on 2026-11-17. The [release issue](https://github.com/driftframestudios/source-of-truth-systems/issues/6) carries the exact artifact and hosted observations. Future releases repeat the receiving checks for their own selected files.
## Source and focused proof
- [Preflight workflow](#source-107c0b32e403) and [activation workflow](#source-192089dc8012) own invocation, permissions, artifact transport and retention.
- [Release tools](#source-a247aea5371e) own accepted coordinates, finite config, deterministic file manifest and activation validation.
- [Focused tests](#source-fb738fe5956c) distinguish altered files, missing paths, mismatched source/tag/receipt, another run attempt and unsafe path material. Run `node --test tests/documentation-release.test.mjs`; semantic Actions validation also uses `actionlint` against both workflow files.
- [Documentation implementation](#document-docs-site-implementation-md-994b21e246e5) owns article generation and both build profiles. [Protected review](#source-f32a9eda0632) owns branch/tag rules and activation prerequisites.
Official references: [custom Pages workflows](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages), [cross-run artifact download](https://github.com/actions/download-artifact), [Pages artifact preparation](https://github.com/actions/upload-pages-artifact), [Pages deployment](https://github.com/actions/deploy-pages). Pages receives static files; Node and GraphQL continue through the application deployment.
## `docs/shareable-navigation.md`
Source document: `docs/shareable-navigation.md`.
# Shareable application views
A visitor can copy the current address to reopen a section, Corridor or Plate scene, Plate overview or Sample history, and the selected Plate lens. The existing interface supplies these choices; the URL follows them. A plain application address opens Lanes/Corridor. A valid shared address opens its declared view on first load and reload.
## Finite address contract
| Query key | Accepted values | Default |
| --- | --- | --- |
| `section` | `map`, `lanes`, `specimens`, `cohort`, `qc`, `biomarkers`, `sources`, `requirements`, `artifacts`, `comparisons`, `decisions`, `release-plan`, `presentations`, `profile` | `lanes` |
| `scene` | `corridor`, `plate` | `corridor` |
| `plate` | `overview`, `history` | `overview` |
| `lens` | `status`, `kind`, `storage`, `athena` | `status` |
For example, `/?scene=plate&plate=history&lens=storage` opens Sample history through the Storage lens. `/?section=requirements` opens the existing Requirements receiver; its internal identifier remains `instructions`. Release plan likewise retains its internal `next-arc` identifier.
`services/navigation/navigationUrl.ts` parses at most 1,024 query characters and accepts known values of at most 32 characters. Duplicate known keys or an unsupported known value refuse the complete navigation input and recover to Lanes/Corridor. Unknown keys carry no navigation authority. Serialization emits only declared nondefault values, in a stable order. Canonicalization removes unrelated query keys and fragments; history entries carry a null state payload.
The address contains view choices. Persona, role, environment, grants, workspace identity, cookies, record metadata, editor text and free-text search retain their existing owners and stay outside this codec. Selected wells and results also remain local exploration state; sharing an exact record requires a separately bounded extension. Documentation article navigation has its own receiving surface.
## Ownership and browser travel
`ExplorationProvider` owns section, scene and Plate preferences above both responsive workspaces. `NavigationHistory`, mounted beneath `GuideProvider`, observes those owners. Section or scene changes add a browser return point with `pushState`; Plate mode and lens changes replace the current point. Initial canonicalization also uses `replaceState`.
Back and Forward synchronously close the guide and invalidate its pending selection authority before the existing state owners receive the parsed address. A delayed history result can populate its scoped data cache, while the visitor's chosen section remains in control. The desktop shell restores a prior Corridor query and releases its return rail on browser travel. Accepted records and permission scenarios retain their independent lifetime.
Mobile continues to provide Corridor and Plate. A desktop-only section remains selected in shared state while the compact layout shows the current scene; widening returns to that section. Choosing Corridor or Plate explicitly on mobile selects Lanes. A Plate URL opens the 3D representation at either size; the mobile touch-board choice remains a local display preference.
## Source draft continuity
`services/sourceEditor.ts` keeps unfinished Source title, summary and tags in the app session, keyed by exact source identity and workspace namespace. Section navigation, browser travel and responsive remounts retain an open editor. Hiding and reopening the same draft retains its original expected revision, so an intervening accepted edit still produces the normal conflict response. Cancel discards that source's draft; a confirmed Save closes only its submitted editor generation. Reload ends unfinished in-memory drafts. Hosted accepted metadata retains its separate workspace recovery.
Explicit workspace recovery rebases the currently open draft to the new revision namespace while preserving its text for review. Opening a dormant draft in a different namespace starts from that workspace's accepted metadata. The existing Source command owner checks workspace generation, workspace identity and current permission scope before publishing an asynchronous completion. URL navigation neither accepts an edit nor changes those checks.
## Focused evidence
`tests/navigation-url.test.mjs` distinguishes finite input, ambiguous/refused input, exclusion of unrelated data and push/replace semantics. `tests/source-editor.test.mjs` exercises retained text and expected revision, stale editor completion, cancellation and namespace recovery. Existing Source workspace tests continue to cover late responses, exact retries and permission changes.
`tests/browser/shareable-navigation.spec.mjs` receives a shared link in the actual Plate, crosses responsive layouts, returns through Back/Forward to an unfinished Source draft, and takes control during delayed guided history. The build-dependent startup test checks that the bridge preserves the deferred desktop/Plate delivery boundary. These are application navigation checks; external hosting and documentation publication retain their own delivery checks.
[Application owners](#source-27d865c285d9) · [Source recovery](#document-docs-visitor-workspaces-md-49294a63218a) · [Documentation](#document-docs-readme-md-0b5ca119d2be)
## `docs/site/graphql-reference.md`
Source document: `docs/site/graphql-reference.md`.
# GraphQL reference
This reference is generated from the schemas and registered operations used by the server. The public endpoints accept their registered operation hashes; the local-only explorer retains its existing development boundary.
## Plate and Corridor reads
Endpoint: `/graphql`. Source: `server/graphql/schema.graphql`.
### Schema
```graphql
"""
Public synthetic scenarios. Canonical policy scopes Plate records and fields;
Corridor describes the shared workflow.
"""
type Query {
dataSource: DataSource!
corridor: Corridor!
plate(id: ID!): Plate
well(plateId: ID!, id: ID!): Well
result(id: ID!): Result
}
enum DataMode {
STORED
EXAMPLE
}
type DataSource {
mode: DataMode!
}
type PageInfo {
endCursor: String
hasNextPage: Boolean!
}
type Corridor {
id: ID!
asOf: String!
lanes(first: Int = 20, after: String): LaneConnection!
cards(laneId: ID, first: Int = 20, after: String): CardConnection!
connections(first: Int = 20, after: String): WorkflowConnection!
}
enum LaneStage {
wet_lab
dry_lab
interpretation
}
enum CardKind {
process
state_major
state_minor
control
nested
}
enum ConnectionKind {
flow
reciprocal
review
deferred
}
type Lane {
id: ID!
label: String!
shortLabel: String!
description: String!
stage: LaneStage!
order: Int!
color: String!
accentColor: String!
}
type Card {
id: ID!
label: String!
kind: CardKind!
position: Float!
note: String
lane: Lane!
}
type WorkflowLink {
id: ID!
kind: ConnectionKind!
from: Card!
to: Card!
}
type LaneEdge {
cursor: String!
node: Lane!
}
type LaneConnection {
edges: [LaneEdge!]!
totalCount: Int!
pageInfo: PageInfo!
}
type CardEdge {
cursor: String!
node: Card!
}
type CardConnection {
edges: [CardEdge!]!
totalCount: Int!
pageInfo: PageInfo!
}
type WorkflowEdge {
cursor: String!
node: WorkflowLink!
}
type WorkflowConnection {
edges: [WorkflowEdge!]!
totalCount: Int!
pageInfo: PageInfo!
}
type Plate {
id: ID!
asOf: String!
rows: Int!
columns: Int!
wells(first: Int = 20, after: String): WellConnection!
}
enum WellRole {
sample
positive_control
negative_control
empty
}
enum Consent {
active
pending
rescinded
expired
}
type Well {
"""
Coordinate within its plate, for example C3. Use plateId with id for lookup.
"""
id: ID!
plateId: ID!
asOf: String!
row: Int!
column: Int!
role: WellRole!
sampleId: ID
assay: String
consent: Consent
contaminationProbability: Float
corridorCard: Card
history(first: Int = 20, after: String): ResultConnection!
}
enum ResultKind {
primary
top_up
reprep
reanalysis
longitudinal
matched_normal
orthogonal
reflex
control
}
enum ResultStatus {
reportable
superseded
failed_qc
in_progress
held
cancelled
informational
}
type Result {
id: ID!
wellId: ID!
sequence: Int!
kind: ResultKind!
status: ResultStatus!
title: String!
label: String!
assayLabel: String!
specimenType: String!
pipeline: String!
runDate: String!
reason: String!
finding: String
consent: Consent!
physicalPlateId: ID!
physicalWellId: ID!
supersedes: Result
flowCell: String
trigger: ResultTrigger
metrics: [ResultMetric!]!
ctDna: CtDnaReadout
minWriteRole: WriteRole!
specimenId: ID
patientCode: String
seriesLabel: String
artifactsRestricted: Boolean
artifacts(first: Int = 20, after: String): ArtifactConnection!
}
enum WriteRole {
viewer
analyst
reviewer
lab_operator
arc_lead
auditor
admin
}
enum MetricComparator {
gte
lte
}
type ResultMetric {
key: String!
label: String!
value: Float!
unit: String!
target: Float
comparator: MetricComparator
}
type ResultTrigger {
source: String!
refId: String
detail: String!
}
type CtDnaReadout {
detected: Boolean!
meanVafPct: Float!
tracked: Int!
detectedCount: Int!
mtmPerMl: Float
emerging: String
}
enum RestoreState {
in_progress
restored
}
enum RestoreTier {
expedited
standard
bulk
}
type ArtifactRestore {
state: RestoreState!
tier: RestoreTier!
requestedAt: String!
readyAt: String
expiresAt: String
}
enum FileKind {
qc
vcf
calls
gvcf
bam
cram
fastq
idat
}
type File {
"""Stable object key: reused files keep the same identity across results."""
id: ID!
kind: FileKind!
"""
Integer byte count represented as Float because GraphQL Int is signed 32-bit.
"""
sizeBytes: Float!
createdAt: String!
lifecycleRuleId: ID!
}
type ArtifactReference {
id: ID!
file: File!
reusedFrom: Result
legalHold: Boolean!
restore: ArtifactRestore
}
type WellEdge {
cursor: String!
node: Well!
}
type WellConnection {
edges: [WellEdge!]!
totalCount: Int!
pageInfo: PageInfo!
}
type ResultEdge {
cursor: String!
node: Result!
}
type ResultConnection {
edges: [ResultEdge!]!
totalCount: Int!
pageInfo: PageInfo!
}
type ArtifactEdge {
cursor: String!
node: ArtifactReference!
}
type ArtifactConnection {
edges: [ArtifactEdge!]!
totalCount: Int!
pageInfo: PageInfo!
}
```
### Approved operations
#### CorridorCards
SHA-256: `9bb1bbd6e3f78dbf066a58336ecec83c6febe4a8212132fc997c72cf356b3f4b`
```graphql
query CorridorCards($laneId: ID, $first: Int = 20, $after: String) {
corridor {
cards(laneId: $laneId, first: $first, after: $after) {
totalCount
pageInfo { endCursor hasNextPage }
edges { cursor node { id label kind position note lane { id label } } }
}
}
}
```
#### CorridorConnections
SHA-256: `65d1e68b433f5f0ea2e24c44b18eb4b8745dbae10a0685e5241bef8f461f517b`
```graphql
query CorridorConnections($first: Int = 20, $after: String) {
corridor {
connections(first: $first, after: $after) {
totalCount
pageInfo { endCursor hasNextPage }
edges { cursor node { id kind from { id label } to { id label } } }
}
}
}
```
#### CorridorOverview
SHA-256: `91283eb7184380b092a2d6855b7d906d146907bb2a687395c6d9865c8efce12a`
```graphql
query CorridorOverview($first: Int = 20, $after: String) {
corridor {
id
asOf
lanes(first: $first, after: $after) {
totalCount
pageInfo { endCursor hasNextPage }
edges { cursor node { id label shortLabel description stage order color accentColor } }
}
}
}
```
#### PlateHistory
SHA-256: `a66a718f0ba28b3532287d3b6e481fb0502f88e98b0c2ea63bc677309f480cf2`
```graphql
query PlateHistory($plateId: ID!, $id: ID!) {
dataSource {
mode
}
well(plateId: $plateId, id: $id) {
id
plateId
asOf
row
column
role
sampleId
assay
consent
contaminationProbability
history(first: 50) {
totalCount
pageInfo {
hasNextPage
}
edges {
node {
id
wellId
sequence
kind
status
label
title
specimenType
assayLabel
physicalPlateId
physicalWellId
flowCell
pipeline
runDate
reason
finding
consent
minWriteRole
artifactsRestricted
specimenId
patientCode
seriesLabel
trigger {
source
refId
detail
}
supersedes {
id
}
metrics {
key
label
value
unit
target
comparator
}
ctDna {
detected
meanVafPct
tracked
detectedCount
mtmPerMl
emerging
}
artifacts(first: 8) {
totalCount
pageInfo {
hasNextPage
}
edges {
node {
legalHold
reusedFrom {
id
}
file {
id
kind
sizeBytes
createdAt
lifecycleRuleId
}
restore {
state
tier
requestedAt
readyAt
expiresAt
}
}
}
}
}
}
}
}
}
```
#### PlateOverview
SHA-256: `f84d7502ab4239349b2d4c49ccf9b3713552919cc51f54fbcd249e052af67fef`
```graphql
query PlateOverview($id: ID!, $first: Int = 24, $after: String) {
plate(id: $id) {
id asOf rows columns
wells(first: $first, after: $after) {
totalCount
pageInfo { endCursor hasNextPage }
edges {
cursor
node { id plateId row column role sampleId assay consent contaminationProbability corridorCard { id label } }
}
}
}
}
```
#### ResultDetails
SHA-256: `e24228967b9e4dda850dc47ec855ce192a97d365dd251bf23ea4e62c6adf6243`
```graphql
query ResultDetails($id: ID!, $first: Int = 20, $after: String) {
result(id: $id) {
id wellId title assayLabel specimenType pipeline runDate reason finding consent
artifacts(first: $first, after: $after) {
totalCount
pageInfo { endCursor hasNextPage }
edges { cursor node { id legalHold reusedFrom { id } file { id kind sizeBytes createdAt lifecycleRuleId } } }
}
}
}
```
#### WellHistory
SHA-256: `0eacd6ad7207bb05061e7facfc0af484751ca0e2ff9b491e451abf16f07cc6b4`
```graphql
query WellHistory($plateId: ID!, $id: ID!, $first: Int = 12, $after: String) {
well(plateId: $plateId, id: $id) {
id plateId
history(first: $first, after: $after) {
totalCount
pageInfo { endCursor hasNextPage }
edges {
cursor
node {
id sequence kind status label title runDate pipeline reason finding
physicalPlateId physicalWellId
supersedes { id }
}
}
}
}
}
```
## Disposable Source workspaces
Endpoint: `/workspace/graphql`. Source: `server/workspaces/schema.graphql`.
### Schema
```graphql
"""An isolated, expiring workspace for public example edits."""
type Query {
workspaceStatus: WorkspaceStatus!
workspaceSnapshot: WorkspaceSnapshot!
workspaceSource(id: ID!): WorkspaceSourceResult!
workspaceHistory(sourceId: ID!, limit: Int = 20): WorkspaceHistoryResult!
}
type Mutation {
startWorkspace: WorkspaceStatus!
resetWorkspace: WorkspaceStatus!
saveSource(input: SaveSourceInput!): WorkspaceCommandResult!
restoreSource(input: RestoreSourceInput!): WorkspaceCommandResult!
}
enum WorkspaceCode {
OK
LOCAL
ABSENT
EXPIRED
DENIED
INVALID
CONFLICT
QUOTA
UNAVAILABLE
MISSING
}
type VisitorWorkspace {
id: ID!
createdAt: String!
expiresAt: String!
eventCount: Int!
}
type WorkspaceSource {
id: ID!
revision: Int!
title: String!
description: String!
tags: [String!]!
}
"""
The selected example persona, separate from the server-issued workspace.
"""
type ScenarioActor {
principalId: String!
roleId: String!
environment: String!
}
enum WorkspaceAction {
save
restore
}
type WorkspaceEvent {
id: ID!
sourceId: ID!
action: WorkspaceAction!
actor: ScenarioActor!
createdAt: String!
expectedRevision: Int!
resultRevision: Int!
}
type WorkspaceStatus {
code: WorkspaceCode!
message: String!
available: Boolean!
workspace: VisitorWorkspace
}
type WorkspaceSnapshot {
code: WorkspaceCode!
message: String!
workspace: VisitorWorkspace
sources: [WorkspaceSource!]!
}
type WorkspaceSourceResult {
code: WorkspaceCode!
message: String!
workspace: VisitorWorkspace
source: WorkspaceSource
}
type WorkspaceHistoryResult {
code: WorkspaceCode!
message: String!
workspace: VisitorWorkspace
events: [WorkspaceEvent!]!
}
type WorkspaceCommandResult {
code: WorkspaceCode!
message: String!
workspace: VisitorWorkspace
source: WorkspaceSource
changed: Boolean!
replayed: Boolean!
}
input SourceMetadataInput {
title: String!
description: String!
tags: [String!]!
}
input SaveSourceInput {
id: ID!
expectedRevision: Int!
idempotencyKey: ID!
metadata: SourceMetadataInput!
}
input RestoreSourceInput {
id: ID!
expectedRevision: Int!
idempotencyKey: ID!
}
```
### Approved operations
#### WorkspaceStatus
SHA-256: `7a1850715aa07dc86311bf476a7fbe06047781971e518d71d82eac011b211923`
```graphql
query WorkspaceStatus {
workspaceStatus {
code
message
available
workspace {
id
createdAt
expiresAt
eventCount
}
}
}
```
#### WorkspaceSnapshot
SHA-256: `93e0e9d023b642a6f68e2c986ef87cb5650dd1002b138ed349a7c2e8931936c6`
```graphql
query WorkspaceSnapshot {
workspaceSnapshot {
code
message
workspace {
id
createdAt
expiresAt
eventCount
}
sources {
id
revision
title
description
tags
}
}
}
```
#### WorkspaceSource
SHA-256: `b27c468d58e81eac92cb14c1bdb6d2283c1158db932a6d3cac4779d9affce616`
```graphql
query WorkspaceSource($id: ID!) {
workspaceSource(id: $id) {
code
message
workspace {
id
createdAt
expiresAt
eventCount
}
source {
id
revision
title
description
tags
}
}
}
```
#### WorkspaceHistory
SHA-256: `6972326894590e55fe2d41d38592d5c0eadd546dec210e0139266f07155d994e`
```graphql
query WorkspaceHistory($sourceId: ID!, $limit: Int = 20) {
workspaceHistory(sourceId: $sourceId, limit: $limit) {
code
message
workspace {
id
createdAt
expiresAt
eventCount
}
events {
id
sourceId
action
actor {
principalId
roleId
environment
}
createdAt
expectedRevision
resultRevision
}
}
}
```
#### StartWorkspace
SHA-256: `d2d0cfc354979318c173c8a6be4746ff1689c98d99f0374d9f6e59b9b53b128a`
```graphql
mutation StartWorkspace {
startWorkspace {
code
message
available
workspace {
id
createdAt
expiresAt
eventCount
}
}
}
```
#### ResetWorkspace
SHA-256: `adf6dfa8bef0b90ae15dc7abbcbf76be1e1ff4dfa286bc5d3a403d34410eebcd`
```graphql
mutation ResetWorkspace {
resetWorkspace {
code
message
available
workspace {
id
createdAt
expiresAt
eventCount
}
}
}
```
#### SaveSource
SHA-256: `b0882602289162289c8618be4e0070dcdcb36700ef6a1cb7229c68191b24d130`
```graphql
mutation SaveSource($input: SaveSourceInput!) {
saveSource(input: $input) {
code
message
changed
replayed
workspace {
id
createdAt
expiresAt
eventCount
}
source {
id
revision
title
description
tags
}
}
}
```
#### RestoreSource
SHA-256: `de7aa872ae7d9f097111e2b7e18bee96d4d88db7b7514a28dc8c1aa80bcde2c3`
```graphql
mutation RestoreSource($input: RestoreSourceInput!) {
restoreSource(input: $input) {
code
message
changed
replayed
workspace {
id
createdAt
expiresAt
eventCount
}
source {
id
revision
title
description
tags
}
}
}
```
## Send an approved operation
Use the hash above with the variables declared by that operation. The request's current scenario and workspace cookie still determine its permission and storage scope. This documentation sends no requests or commands.
```json
{
"extensions": {
"persistedQuery": {
"version": 1,
"sha256Hash": ""
}
},
"variables": {}
}
```
## `docs/site/implementation.md`
Source document: `docs/site/implementation.md`.
# Extend the documentation entry
`docs/content-manifest.json` admits articles, their reading metadata, the two build profiles and the broader source population published in the LLM text bundle. An author edits Markdown or the owning schema, then rebuilds the projection.
## Two receiving profiles
- `npm run build` creates the application, private server projection and documentation at `/docs/`. The docs build owns `dist/docs/`; it leaves the application's initial bundle and manifest intact.
- `npm run build:foundation` creates the same articles at the site root in `dist-foundation/`, with `https://kindlight.foundation` as its canonical origin. This command builds static files; publication and host configuration remain explicit owner actions.
- `npm run build:docs` rebuilds only the `/docs/` projection after dependencies are installed. The ordinary Node server still needs its application and server builds.
Both local build routes work from an ordinary source ZIP without Git, a database or network documentation fetches. The separate [tagged Pages release](#document-docs-runbooks-tagged-documentation-release-md-33af7f4666be) uses Git to bind accepted app, publication and trusted workflow revisions to one verified static artifact. Application origin comes from `.figma/make/site.json`; the documentation manifest supplies the separate foundation origin and base. Change those owners when the receiving host changes.
## Add an article
Add one unique slug, source, title, description and navigation group to the manifest. The build reads only ordinary source files and rejects symlinked inputs. Keep the title and description useful to a reader choosing a route. Relative links to admitted articles become ordinary article links; other Markdown and source paths remain visible repository references. The footer links to the complete text bundle explicitly; plain-text fragments are machine-readable coordinates rather than browser article anchors.
The build-time Markdown renderer keeps raw HTML as text and admits ordinary HTTP(S), mail and owned document links. It renders fenced code as escaped text. Authors use Markdown instead of executable MDX. The article is complete HTML before JavaScript starts; a separate React entry mounts only the existing ThemeProvider and appearance selector. App, scene fixtures, session owners and GraphQL clients remain outside that entry.
## Keep the graph reference authoritative
`server/graphql/schema.graphql` and `server/workspaces/schema.graphql` own the schemas. Their operation registries validate the approved source documents and compute hashes from the exact original bytes. The documentation generator uses those owners to produce the reference and LLM companion. Readers can copy an approved hash and supply its declared variables; these pages execute no API requests or mutations. Production operation admission and the local-only explorer remain unchanged.
## Receive a request
The Node server reads the generated route manifest and serves each article with its own document policy and `no-cache`. Slashless admitted routes redirect to their canonical slash form; unrelated paths keep their normal 404. Static article assets remain under the documentation base. The standalone build includes a meaningful static 404 page. Appearance reuses the application's preference key and typed palette without importing its state. Vite generates the initial CSS variables from that same typed dark theme, so first paint and the interactive selector share one color authority.
## Verify a change
Build both profiles, run the documentation and startup tests, then inspect one direct article and an internal link at mobile and desktop widths. Change appearance and refresh the article. The build manifest proves the docs entry stays separate from the application's initial import closure. HTTP checks cover exact routes, HEAD, cache/CSP and unknown paths. These observations establish local build and serving behavior; a published host remains its own receiving check.
The implementation follows [Vite's multi-page build](https://v6.vite.dev/guide/build.html#multi-page-app), [Markdown-it's safe defaults and renderer](https://github.com/markdown-it/markdown-it), and [React root isolation](https://react.dev/reference/react-dom/client/createRoot). Vite 6 uses `build.rollupOptions.input`; the separate output directory and base preserve each receiver's asset paths.
## `docs/site/index.md`
Source document: `docs/site/index.md`.
# Build with Source of Truth
Follow a sample from intake to a result, then follow the code that makes that exploration possible. Source of Truth is a visual, interactive life sciences showcase built around synthetic workflows and recorded histories.
## Start with something you can run
The [live application](https://kindlight.ai) is available to explore. Use the local setup below with a repository clone; if GitHub requests access, ask the maintainer for an invitation.
[Run the example](#document-docs-getting-started-md-31bcba2ccafa), select a well in Plate, and compare its results. The bundled scenario works without a database or an account. The Node server adds the real GraphQL boundaries used by the production application.
## Find the owner of a change
| You want to… | Start here |
| --- | --- |
| Choose persistence for an adaptation | [Database choices](#document-docs-database-choices-md-a44edbfece29) |
| Add or inspect a read | [GraphQL reads](#document-docs-graphql-read-api-md-03dad145256f) and the [generated reference](#document-docs-site-graphql-reference-md-197b9b3977ee) |
| Preserve policy through a command | [Permission scenarios](#document-docs-permission-scenarios-md-cbea28e234a3) |
| Extend colors without moving a scene | [Theme contracts](#document-docs-theme-contract-md-9253d68c555a) |
| Choose evidence for a change | [Focused checks](#document-docs-runbooks-selective-check-delivery-md-0b5f34c348ca) |
| Deliver the application | [Deployment](#document-docs-deployment-md-7f6254f34e12) |
The application separates its visual scenes, accepted browser state, canonical commands and server adapters. A small change belongs with the owner that can explain its effect and recovery. [The documentation index](#document-docs-readme-md-0b5ca119d2be) leads to the complete set of source contracts.
## Work from explicit examples
Synthetic records support exploration of questions such as “Why was this sample rerun?” and “Which result used this file?” [Fixture provenance](#document-docs-fixture-provenance-md-8ff275b9c7d1) explains what those examples establish. Production clinical decisions, verified private accounts and real patient data require their own receiving design and authority.
## Contribute a focused improvement
Describe the behavior a person can observe, change its owning source, and choose a check that distinguishes the intended outcome from a plausible fault. The [testing method](#document-agents-skills-test-suite-composition-skill-md-412c39ca5e33) and local runbooks support that route. Repository instructions document collaboration; application permission checks retain runtime authority.
## `docs/source-discovery.md`
Source document: `docs/source-discovery.md`.
# Sources, saved metadata and local search
Sources keeps its type filters, source cards and selected record usable together at desktop and compact laptop widths. A search appears beside the records it actually filters. This contract records the resulting collection, selection and edit behavior.
## Sources composition
The left column uses a bounded 260–340px width. Search, wrapping type buttons and the result count retain their height; the source list receives the remaining scrollable space. The right record has a separate vertical scroll area, a bounded reading width and wrapping relationship descriptions. The two authority groups retain their paired presentation. The shared appearance roles supply surfaces, text, focus and confidence accents.
The workspace grid explicitly bounds both its columns and row. Its Radix viewport retains scrolling; a Sources-only rule replaces Radix's internal table measurement wrapper with a wrapping block. This prevents content width and height from forcing the inspector beyond its receiving viewport. The shared ScrollArea component and other consumers keep their existing behavior.
Selecting a card opens that exact source; selecting it again closes the detail. Filtering changes the list while leaving an already inspected source available. A direct Corridor reference clears the local query and type filter, selects the exact source and retains the existing return route. The count names the filtered and total records; an empty result explains how to recover.
Edit metadata opens a compact form in the selected source. Display title, summary and tags use the current Source command owner, with permission and expected revision checked at acceptance. With the additive workspace schema installed, an explicit first save starts a disposable visitor workspace and saves those fields through GraphQL. The compact status strip names saved/local/unavailable state, expiry and reset; a small disclosure shows that source's saved edits. Source IDs, authority scopes, role, status, confidence and source-update date retain their bundled provenance. The list, local search, relationships and mobile exact-source receiver read the accepted projection. Cancel retains the accepted record; a refused save keeps the draft visible. The selected source, registry filters and unfinished metadata draft survive section return, Back/Forward and responsive layout changes. [Shareable navigation](#document-docs-shareable-navigation-md-bcfb7b016c1b) describes the in-memory draft owner, cancellation and workspace namespace boundaries.
Restore bundled source reads that one source's canonical metadata and reports whether anything changed. It uses the same local or hosted command route as Save. This recovery is a guarded metadata edit, not an external connector refresh or a freshness timestamp. A valid workspace cookie restores saved Source metadata after reload; other local workflow owners retain their existing session lifetime. Reset workspace revokes only that browser's saved Source overrides. It is distinct from Access Grid's Reset scenario grants.
`services/sourceEditor.ts` owns app-session draft text and editor generations separately from accepted records. `services/sourceSession.ts` owns validated field limits, immutable source revisions and command-time permission checks. `sourceWorkspace.ts` owns hydration, in-flight commands, exact retry identity and workspace generations; `workspaceTransport.ts` owns finite operation identities and the same-origin request. `sourceSessionContext.tsx` binds these to the existing lazy app-instance resource; `useSourceRecords` supplies accepted records to read-only receivers. Hydration precedes a hosted write. Late responses cannot replace a newer revision or another workspace. A stale form preserves its draft and the current accepted record. Public synthetic source references use the workspace-edit capability with an owner-resolved ID; their source-authority matrix remains separate from user-access grants.
The explicit `LOCAL` response preserves browser-session editing before workspace installation, and the Vite source-development mode remains intentionally local. A network failure or installed-database outage keeps the hosted draft pending instead of reporting local success. Expiry offers a new disposable workspace. [The workspace contract](#document-docs-visitor-workspaces-md-49294a63218a) describes cookie ownership, limits, migration and recovery.
The Pipeline configuration manifest is documentary Source metadata. Its form edits title, summary and tags; it does not parse or execute YAML. React renders accepted text as text. [The input-boundary assessment](#document-docs-research-input-boundaries-md-c7dbe8e1d24d) records this distinction from HTML sanitation and executable configuration.
## Search audit and receiving owners
| Surface | Previous behavior | Current receiving behavior |
| --- | --- | --- |
| Desktop shell, all 14 sections | A shared input appeared on every section. Only Corridor cards and Profile's Error Lab read it. | The generic shell input is removed; appearance, environment and current-view identity retain their places. |
| Lanes → Corridor | Shared query matched card label, note, ID and lane ID. | The existing query and matching remain in the Corridor toolbar. The control is absent in Plate, whose scene did not consume it. Corridor return still restores the saved query. |
| Sources | A working local input duplicated the inert shell input; matching did not consistently trim or normalize every field. | One local Find sources control matches title, ID, description, display type/role and tags with the shared trimmed, case-insensitive matcher. Type filters compose with the query. |
| Specimens | A local search matched specimen ID, patient, indication, material and assay; shell search was inert. | The local search, stage/consent filters and expandable records remain unchanged. |
| Profile → Error Lab | The shell query filtered the historical log and could carry unrelated Corridor text; changing it could leave pagination beyond the result set. | Find log entries sits beside that log. Its local query matches code, title, message and subject ID; changing or clearing it returns to page one. Other Profile tabs show their own controls. |
| Mobile Corridor | A compact local search matched card name, note and ID within the selected lanes. | Existing touch search and filters remain unchanged. |
| Map, Cohort Builder, Quality Control, Biomarkers, Requirements, Artifacts, Comparisons, Decisions, Release plan, Presentations | The shell input changed shared text without changing those views. | That inert control is removed. Existing map selection, cohort rules, biomarker category/tier, requirement status/category/release/sort, comparison mode, decision release/status, artifact view and presentation selection remain in their owners. |
`components/SearchField.tsx` provides the controlled input, explicit clear action and focus treatment for Sources, Corridor and Error Lab. Each receiving view owns what matches and how its results appear. `services/search.tsx` retains the Corridor query used by the desktop return route and the small deterministic matcher; it is not a global result index.
## Future discovery boundary
A useful global search would project typed entries from the canonical record owners: stable ID, human title, record kind, searchable text and an exact navigation target. For this example's small collections, deterministic in-memory matching and grouped results are sufficient. Exact IDs and title matches can lead the result order; the existing record resolver can open a supported destination and preserve return context. Permission-aware result visibility belongs with the access foundation, before a global index exposes records from multiple domains.
AI-assisted questions are a separate explicit operation. A future implementation can receive the same authorized source projection and return source-linked answers while keeping ordinary find/filter actions deterministic. Current-view search creates no inference request, external source fetch or new persistence boundary. Accepted metadata preserves source identity and relationships. A future remote refresh requires a named connector and an observed response before it can report new source content.
## Evidence
`tests/browser/source-discovery.spec.mjs` checks all seven Source type controls at 1024 and 1512px, trimmed case-insensitive ID search, composed filtering, empty recovery, operable metadata and bundled-restore actions, all eight source records' horizontal fit and locally reachable final content. It also checks Corridor/Plate search scope, independent Error Lab pagination and the absence of inert searches on other sections. `tests/source-session.test.mjs` covers exact edits, preserved provenance, late permission changes, stale revisions, bounded input and restoration. `tests/browser/source-operations.spec.mjs` covers saved metadata, retained selection, a denied draft save, mobile exact-source reading and bundled recovery. The existing exact-record Corridor journey in `core.spec.mjs` verifies return context after filtering a source.
`tests/source-workspace.test.mjs` observes hydration, pending retries, revision ordering and workspace recovery. The opt-in real-database journey in `tests/browser/source-workspace.spec.mjs` exercises saved edits after reload, separate browser ownership, reset, and literal rendering of HTML/SQL/YAML-looking text. `tests/mysql-workspace-http.mjs` connects the production HTTP route to the actual disposable MySQL store. Settled captures compare the Sources family before and after the repair. These checks establish the named records and viewports in the local production build; operator upload remains the hosted receiving check.
## `docs/specimen-table.md`
Source document: `docs/specimen-table.md`.
# Specimen cards and cell exploration
Specimens starts with its visual masonry atlas: accession and patient, indication and material, consent, coverage, recorded timeline and current workflow. A Cards / Table switch gives the same collection a compact comparison view. Search, filters and sorting belong to that collection, so switching representations retains the visitor's scope. Accepted records stay with the shared session owner.
**Supersession:** topic-specific cell dialogs replace the earlier inline expanding-row interpretation. Selecting a table cell now opens that cell's information group in a modal. The row remains compact. This description preserves the supersession; topic-specific dialogs define the current interaction contract.
## Reading and interaction contract
Eight columns distinguish specimen/patient, assay/material, sample, review, order, quality, history and consent/region. The first column carries the row identity with `th scope="row"`; every column has `th scope="col"`. A cell is a native button whose accessible name includes the exact accession and destination topic. Table headers sort ascending, descending, then return to original order; `aria-sort` reflects the selected direction. A shared Sort by control offers the same ordering in Cards.
Collection search covers owned display terms and literal identifiers, including patient, well, assay and current states. Assay, recorded stage, consent, priority, order and quality facets combine. The visible count reflects the filtered collection; the summary rail labels whole-register totals. Clear filters restores the collection without changing the chosen sort. Reset sort restores canonical source order. An empty result offers a clear return.
The selected cell opens one live specimen and the relevant topic: Sample context, Sample workflow, Clinical review, Order workflow, Quality & coverage, Recorded history, or Consent & provenance. Topic navigation stays inside that record. Previous/Next follows the current filtered and sorted collection while retaining the topic. A consent cell explains the consent source, geography and data class; it does not infer a file relationship from a well coordinate alone.
The dialog resolves its selected accession against all accepted records. If an action removes the record from the active filter, the modal remains open, displays the accepted result and states “Outside current filters.” Closing returns focus to the originating cell or card control; if that control has left the collection, focus returns to the register. Escape, the close control and the modal overlay all use the same dismissal path. Sorting/filtering and scroll position remain in place behind the dialog.
Radix Dialog owns modal semantics, focus containment and Escape. Motion supplies a short spring from the selected control's vicinity and a restrained return. Reduced motion removes the translation/scale transition. The title receives opening focus, the topic rail remains visible, and the body scrolls within the viewport. No record mutation is tied to animation completion.
## Visual fidelity
Masonry preserves the original card hierarchy and varied content heights, with three columns at laptop width, two near the desktop boundary and four on wide screens. Coverage bars, dotted timelines, inline workflow strips, priority chips and consent-colored edges retain the original expression through shared theme tokens. The layout remains native CSS columns; cards keep their whole content together.
The table uses the same navy, teal selection and sky/violet/amber status language. It fits a laptop workspace and allows local horizontal scrolling at the desktop boundary; the identity column and header remain visible. Each cell's whole area is clickable, with a quiet outline on hover and a visible keyboard focus. Status, priority and consent always retain text. Light and High contrast use the existing semantic palette rather than filters over Dark artwork.
The dialog is a compact raised record surface. It keeps identity and topic navigation above the scrolling body and collection navigation below. Zero-valued tumor/variant metrics remain values; unavailable plate assignment reads “Not assigned.” Recorded stage and dated timeline remain source facts, while sample, review and order reflect accepted local changes.
Every specimen metric declares its target direction as `gte` (at least) or `lte` (at most). Cards and expanded quality show that qualifier beside the unchanged raw value, target and unit. The duplication-rate example meets its at-most target; depth, coverage and the remaining supplied examples declare at-least targets. These are synthetic source contracts, independent of metric names or clinical threshold inference. A shared comparison owner supplies both metric color and Cohort Builder's **All metric targets met** predicate and result strip. An empty metric collection remains unassessed rather than satisfying the predicate. QC flags remain separate recorded findings, so meeting one target never clears a flag. This supersedes the inherited rendering that treated every metric target as at-least.
## Table engine decision
| Option | Fit for this register |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Native table with custom sorting/filter state | Small dependency surface; duplicates generic state and ordering machinery as collection operations grow |
| TanStack Table | Headless, typed row models preserve native markup and this application's complete visual ownership |
| AG Grid Community | Mature sorting/filtering and grid interaction; its grid renderer and additional features exceed this ten-record comparison's needs |
| MUI X Data Grid | Integrated styled grid; its Material component model changes the design integration, and the community edition limits combined filters/sorts |
Use **TanStack Table 9.3.1**, pinned with its lockfile. The published package supports React 18 or newer. Register sorting, column filtering and global filtering with only the comparator/functions used here. The view controls the small sorting/filter state and supplies a stable accepted-record collection. Native HTML and source-owned components render the result. Row virtualization, pagination and a second local record store add no value to this complete ten-record register.
The dependency is imported through the deferred Desktop workspace, alongside the existing Radix Dialog and Motion owners. The production manifest and startup budget check verify that initial mobile delivery still excludes the desktop table. The frozen dependency graph and ordinary build own the emitted browser assets.
Sources: [TanStack installation](https://tanstack.com/table/latest/docs/installation), [headless model](https://tanstack.com/table/latest/docs/overview), [sorting](https://tanstack.com/table/latest/docs/framework/react/guide/sorting), [column filtering](https://tanstack.com/table/latest/docs/framework/react/guide/column-filtering), [AG Grid editions](https://www.ag-grid.com/react-data-grid/community-vs-enterprise/), [MUI filtering](https://mui.com/x/react-data-grid/filtering/), [MUI sorting](https://mui.com/x/react-data-grid/sorting/), and [native row/column headers](https://www.w3.org/WAI/tutorials/tables/two-headers/). These sources inform the engine/semantic decision; browser observations establish this composition's behavior and geometry.
## Source ownership and evidence
- `components/views/SpecimenView.tsx` owns the current representation, collection controls, selected accession/topic and source-focus return.
- `components/specimen/specimenCollection.ts` owns typed columns, display topics, facets and search terms; TanStack derives one ordered/filtered collection for both renderers.
- `SpecimenCards.tsx`, `SpecimenCell.tsx` and `SpecimenDialog.tsx` own their respective projections; `SpecimenDetails.tsx` shares coverage, history, consent and workflow modules.
- `services/specimenQuality.ts` owns declared metric comparisons and target wording. `data/index.ts` owns their synthetic values, units and directions; `BooleanBuilderView.tsx` consumes the same comparison for cohort matching and result-strip color.
- `specimen-table.css` owns the atlas, comparison and dialog geometry. Existing theme tokens supply all appearance modes.
- `useSpecimens`, record transitions and `useWriteGate` retain accepted-state and permission authority. The mobile workspace continues to prioritize Corridor and Plate.
Focused browser cases establish default cards, exact topic/record association, keyboard open/close/focus return, independent expected date order, combined filters, empty recovery, accepted edits visible in both forms, held-consent refusal, and retained modal state when an edit leaves its filter. Existing permission, theme and navigation journeys continue against the new representation. Typechecking, production build and startup checks establish integration and deferred delivery. Visual checks cover laptop/desktop-boundary geometry and the spring landing state; artifacts remain in ignored `.visual-runs`.
## `docs/theme-contract.md`
Source document: `docs/theme-contract.md`.
# Appearance modes
The workspace offers **Dark**, **Light**, and **High contrast** from Appearance controls in both headers. Desktop shows one native radio group with a pressed active segment; compact screens keep the native select menu. Choosing a segment selects exactly one mode, and the native arrow keys move between choices. Dark is the first-visit default. The browser remembers an explicit selection under `sot.appearance`; unavailable or stale storage falls back to Dark. Changing appearance preserves the mounted workspace, accepted record edits, filters, selected wells, camera position, and history actions.
## One theme, shared geometry
`src/app/theme/palettes.ts` owns typed shell, scene, table, and status roles. `createTheme` in `theme.ts` combines the selected mode with optional typed module overrides. Every mode inherits the same geometry. Extend a semantic role in its module and supply its meaning in each mode; keep scene dimensions and motion in their existing owners.
`ThemeProvider` sits above the mobile/desktop branch. It publishes the palette as `--sot-shell-*`, `--sot-scene-*`, `--sot-table-*`, and `--sot-status-*` variables on the document root, including portal content. `theme.css` maps existing utility roles to those variables. `useTheme().theme` supplies concrete six-digit hex colors to canvas and dynamic drawing consumers. Use `withAlpha(color, opacity)` for concrete colors, or CSS `color-mix` for variable-based tints. A CSS variable string cannot take a hexadecimal alpha suffix.
The provider accepts the same typed module overrides as the factory. The Plate domain keeps its result, storage, and query color identities in `stackLens.ts`; its concrete mode-aware paint derivation supplies both discs and legends, with `usePlateColors` sharing those hues with record companions. Dark and Light retain their established domain projection. High contrast maps the green/violet category pair to gold `#ffd166` and sky blue `#87c9ff`, adding a center dot or short bar on otherwise unpatterned faces. A single diagonal identifies failed QC across lenses, suppressing any optional category mark on that face. Consent hold/cancellation take priority; storage textures remain visible beneath the quality mark. Both legend presentations share the same paint projection. The [Plate cue research decision](#document-docs-research-high-contrast-wells-md-bb2bc5d3ea0a) records the narrow scope, alternatives and community feedback questions. Existing Dark utility shades remain intact; alternate-mode utility families receive the shared semantic foreground roles. Environment accents are presentation projections of the existing environment IDs; appearance leaves identity and write policy in their established owner.
| Module | Receiving use |
| --- | --- |
| Shell | Workspace and record surfaces, ordinary text, controls, selected state, borders and focus |
| Scene | Corridor/Plate canvas, grid, particles, scene labels and plate body |
| Table | Specimen header, alternating records, selected rows, detail modules and dividers |
| Status | Success, warning, danger, information and violet category accents; labels and symbols retain their meaning |
Dark retains the navy scene and existing colored paper/ink art. Muted interface text uses a readable member of the same blue-gray family. Light uses pale blue surfaces and dark ink; High contrast uses near-black surfaces, bright text, and stronger dividers. Native controls follow the mode through `color-scheme`. Neither mode changes reference images or applies an inversion/filter to a 3D carrier. Fixed paper placards with their own dark ink remain paired art elements. The unfurled Plate result tray uses two restrained, downward shadow layers in Light mode to separate its record from the scene; Dark and High contrast retain their existing treatment. Shadows belong to the tray surface, leaving preserve-3D carriers and disc geometry unchanged.
`StatusBadge.tsx` owns the shared source, requirement, acceptance and release badges. Each domain value selects a typed status role, or the shell's secondary ink for a neutral label. In Light mode, `record-badge.css` pairs that ink with an opaque 8% tint and a 28% tinted border against the shell surface. This keeps the label readable on ordinary and selected cards without changing badge size or typography. Dark and High contrast retain their existing badge utility paints. The label, rather than its tint alone, identifies the source type, category or state; new variants enter through this shared owner.
## Evidence and extension boundary
`tests/theme.test.mjs` checks all declared ordinary text/surface pairs at 4.5:1 or higher, complete CSS-role coverage, shared geometry, isolated overrides, and preference recovery. `tests/plate-paint.test.mjs` checks category/key agreement, existing semantic-pattern priority and the unchanged Dark/Light pair. Browser coverage switches actual scenes and accepted records between modes, checks retained state, and exercises the compact selector and reload. High contrast Plate inspection includes ordinary-size faces and legends under deuteranopia and achromatopsia emulation. These checks establish the named pairs and journeys; High contrast is a descriptive mode name rather than a claim of universal color-vision compatibility. Simulation invites investigation and user feedback; it does not validate every deuteranomaly severity or replace observation with people. Existing status labels, shapes, and legends remain necessary.
`tests/browser/record-badges.spec.mjs` measures actual rendered Light badge foregrounds and opaque backgrounds in Sources, Requirements and Artifacts at compact-desktop and wide widths, including a selected source. It requires the previously weak S3 Doc, YAML and neutral labels to be present and all observed pairs to reach 4.5:1. Focused before/after inspection at those widths preserves Dark and High contrast paints and badge geometry; independently colored scene markers remain with their domain owner.
Run typecheck, the focused theme tests, the 3D guard, and a production build before the focused browser journey. Compare Corridor, selected Sample history, an expanded Specimen record, and a compact viewport in all modes. Add a pair test when introducing a new informational foreground/background combination. Review any independent domain-art palette at its actual receiving surface.
The implementation follows [React context](https://react.dev/reference/react/createContext) for stable shared selection, [CSS color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme) for native controls, and the foreground/background and redundant-encoding principles in [Contrast Minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) and [Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html). The checks below establish the receiving behavior.
## `docs/visitor-workspaces.md`
Source document: `docs/visitor-workspaces.md`.
# Disposable visitor workspaces
Source metadata edits can belong to one expiring browser workspace while the bundled examples remain shared. This implements the owner's disposable-workspace choice. The workspace cookie proves possession of that sandbox. Verified human identity, private records and real multi-user collaboration remain separate design and acceptance boundaries.
## Ownership and data
The first durable workflow is Source **edit metadata / restore bundled source**. Title, summary and tags pass through the same pure domain preparation used by browser commands. Canonical IDs, provenance, source dates, authority and relationships retain their bundled owners. The selected persona supplies a simulated policy scenario; stored event actors are explicitly scenario actors.
`server/workspaces` owns the provider-specific PostgreSQL and retained MySQL schemas, short-lived write connection, workspace lifecycle, finite GraphQL documents and HTTP session boundary. `src/app/services/sourceSession.ts` owns the Source transition and metadata limits. The private server build exports the canonical Source baseline and this preparation function; GraphQL, SQL drivers and token machinery stay outside the browser bundle.
Each workspace lasts 24 hours from creation. Its rows hold metadata overrides, revisions and accepted command receipts. The limits are 128 active workspaces, 64 changed events and 128 total accepted receipts per workspace. No-op receipts count toward the latter limit so their exact retry result can be retained. Bounded expiry cleanup runs on admission; reset deletes the workspace and scoped children. Expiry immediately denies access, while physical cleanup waits for a later admission or operator maintenance. These bounds suit the low-traffic showcase; they are not a promise of anonymous admission under sustained abuse.
## Request boundary
`/workspace/graphql` accepts only registered, named operations through same-origin JSON POST with `x-sot-workspace: 1`. Batching, multipart bodies, arbitrary documents and production exploration are disabled. The body is bounded to 16 KiB and the response deadline is five seconds. All responses, including errors and deadline responses, use `Cache-Control: no-store`.
The server generates a 256-bit opaque token and stores only its SHA-256 verifier. HTTPS uses the `__Host-sot-workspace` cookie with `Secure`, `HttpOnly`, `SameSite=Strict`, `Path=/` and an absolute expiry. HTTP loopback development uses a separately named cookie. Tokens stay out of URLs, browser storage, API result fields and logs. A workspace row is also bound to its normalized owning origin, including the port, so preview and publish remain independent even when their database is shared.
Admission compares the browser Origin with the incoming Host, allowing the hosting proxy to terminate TLS while avoiding forwarded-host authority. A cross-site request, invalid origin, simple content type or missing custom header is rejected before storage opens. Origin checks mitigate browser CSRF; they do not authenticate a person. Deployment-wide database quotas and a process-level creation throttle bound anonymous allocation. A future account implementation replaces this public ownership boundary with verified identity.
## Acceptance and recovery
Save and Restore carry an expected revision and an opaque command identifier. Current simulated policy and metadata validation run before acceptance, including a retry. The store locks the workspace, compares the current version, and commits the projection and receipt together. Reusing the same identifier and normalized intent returns its original accepted result; reusing it for different intent conflicts. Readers must retain the newer revision if an older receipt returns later.
`WorkspaceStatus` distinguishes an intentionally uninstalled feature (`LOCAL`) from unavailable storage. Existing local Source editing remains the ordinary behavior until the additive workspace schema is explicitly installed. A retained workspace cookie or a failed database connection cannot silently turn a hosted write into local success. Typed absence, expiry, denial, conflict, quota and unavailability let the receiving interface retain a draft and offer the next useful action.
Start reuses a still-valid workspace without extending its lifetime. Reset revokes the current scope and clears its cookie; a later Start creates a new scope. An ambiguous network response can follow a committed transaction, so the client retries the same command identifier. A failed initial Start can leave a bounded, inaccessible workspace until expiry; subsequent explicit creation remains subject to the same quotas.
## Deployment and evidence
The [PostgreSQL clone](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) installs the catalog and workspace schemas through its explicit initializer, then starts the ordinary app with a separate runtime role. Native operators follow the same [schema/grant contract](#document-docs-postgresql-md-a7cc27814ec8). Ordinary startup performs no DDL. Reset in Sources removes only that visitor workspace; a clone-wide database reset is a distinct, explicitly confirmed operator command.
Verify an accepted Source edit survives reload at the same origin with its workspace cookie. App/database restart retains it within the 24-hour lifetime. A trusted backup restores saved rows and receipts; access still requires the original unexpired cookie and origin. Two clones on different localhost ports use separate browser contexts because cookies share a hostname while workspace authorization binds the exact origin.
Domain tests establish validation, provenance and command-time policy. API and HTTP checks exercise finite operations, cookie-derived scope, denied/stale/repeated commands, typed recovery and uncached responses. PostgreSQL engine checks establish migration ownership, rollback, concurrent revision/idempotency/quota behavior and indexed reads. The [clone proof](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) exercises actual process restart, backup recovery, failed-restore preservation and clone reset isolation. A receiving remote host retains its own observation.
The [storage contract](#document-docs-workspace-storage-md-c97549ad8a50) describes expiry, admission and immutable receipts; [PostgreSQL setup](#document-docs-postgresql-md-a7cc27814ec8) names current configuration and recovery. Private-data accounts and lasting clinical audit records remain separate future work.
## `docs/workspace-audit.md`
Source document: `docs/workspace-audit.md`.
# Workspace actions, composition and language
Visitors can inspect records, accept bounded local changes and return to the resulting state across workspace navigation. This fourteen-view assessment connects each visible action to its accepted state and recovery owner.
**Supersession:** the initial audit recorded unavailable Requirements, Artifacts and Decisions actions, view-local Map/QC/Cohort state and disconnected Profile settings. The accepted owners below replace those findings. The subsequent compact-rail and shared-badge findings now have task-specific receiving layouts and a common Light badge treatment. Initial captures preserve the observed pressure points; current command, composition and browser evidence establish the delivered behavior.
## Receiving inventory
| View | Current operations and ownership | Composition and retained boundary |
| --- | --- | --- |
| **Map** | Node selection, two-axis graph scrolling and [retained legal sample/order/review examples](#document-docs-operational-workflows-md-f6abb8b89c02). Requirements counts use accepted release records. | System nodes retain their own identity; work area is context. The graph and lower artifact strip keep their existing geometry. |
| **Lanes** | Corridor search, filters, camera presets/drag, zoom, travel, flags and exact record navigation. Plate has sample/result selection, history framing, lenses and guarded file/query actions. | Shared exploration intent survives resize. [Compact desktop Plate rails](#document-docs-plate-workspace-md-14d2cf5280a5) open over a stable scene; wide rails remain beside it. The [mobile contract](#document-docs-mobile-showcase-md-a1c532f6fcd0) owns portrait scene room and touch receivers. |
| **Specimens** | Masonry and sortable/filterable [table](#document-docs-specimen-table-md-cd6b2fe720d6), topic-specific cell dialogs and accepted sample/order/review events. Explicit metric comparators drive quality summaries. | Canonical record commands enforce current scope. Historical pipeline stage and clinical example values keep their source meaning. |
| **Cohort Builder** | Named [rules](#document-docs-cohort-rules-md-bacccc83d4fa) can be saved, reopened, updated, copied and removed. Matches recompute from accepted specimens/biomarkers; active-consent matches form the eligible cohort. | The [compact tool rail](#document-docs-compact-records-md-8c3453ea976e) switches between Add cards and Rule & saved, with counts above the editor. Saved definitions survive navigation; a desktop layout change retains the editing draft. Patient-data export and remote rule storage have separate owners. |
| **Quality Control** | [Acknowledgement, recorded hold, rerun request and reopen](#document-docs-operational-workflows-md-f6abb8b89c02) update the exact gate and review count. | Responses stay separate from measured metrics, gate status and release holds. Executing laboratory work needs a backend workflow. The stage rail intentionally scrolls horizontally. |
| **Biomarkers** | Category/actionability filters, accepted review events and related specimen consent. | Shared record commands own permission and transitions. Clinical values and therapy prose preserve the supplied examples. |
| **Sources** | Composed search/type filters, exact selection, [metadata editing and bundled recovery](#document-docs-source-discovery-md-40a2d04884a2). Accepted titles and descriptions reach their read-only receivers. | IDs, authority, provenance and source-update dates retain their source owner. Bounded list/detail viewports and [shared readable Light badges](#document-docs-theme-contract-md-9253d68c555a) support inspection. External refresh remains unavailable. |
| **Requirements** | Status/category/release filtering and sorting; [explicit release deferral, selected replacement and restoration](#document-docs-release-workflows-md-9eebdfbf2768). Sidebar, Map and exact-record receivers share accepted state. | Original wording and rationale remain inspectable. Revision checks preserve a newer record when an older command arrives. The final expanded row remains locally reachable. |
| **Artifacts** | Gallery, Lineage and Comparison share [local reference checks and revision proposals](#document-docs-artifact-operations-md-7ff5ea1a7629). Visitors save or discard a proposal; mobile readers show accepted local work. | A [full-area compact record](#document-docs-compact-records-md-8c3453ea976e) returns to its selected gallery card; wide screens retain the side inspector. Recorded acceptance, file identity, hash and size remain separate from metadata preparation and external file execution. |
| **Comparisons** | Mode filtering, paired evidence and [Resolve/Defer/Reopen](#document-docs-comparison-decisions-md-3003b90861d1) with retained decisions and status counts. | Exact comparison identity and the original evidence remain stable. Final-record actions stay within the local scroll viewport. |
| **Decisions** | Release/status filters, source/rationale inspection and [Confirm/Revisit/Restore original](#document-docs-release-workflows-md-9eebdfbf2768). | Accepted status survives navigation; supplied rationale and dates remain historical evidence. Comparison decisions remain a distinct collection. |
| **Release plan** | Curated objective, requirements, sources and review criteria; Preview summary reads accepted requirement statuses and source names. | The packet membership and readiness input remain curated reference material. Publish states its current availability. |
| **Presentations** | Curated briefs, distinct styles, three formats, section selection, pagination and return. | The [presentation contract](#document-docs-presentation-styles-md-b2f82a4fd1a5) retains format/long-title evidence. Future AI-assisted composition is a separate discussion; inspectability makes no new clinical claim. |
| **Profile** | Acting persona/role, audience, validated Access Grid with local grant reset and [consumed appearance/informational-toast preferences](#document-docs-profile-preferences-md-96585d17da7a). Error Lab keeps local search and notice previews. | Grouped navigation moves above compact forms and keeps the actor separate from the inspected person. Required feedback remains visible. Connections and external delivery retain explicit preview/unavailable boundaries; infrastructure stays an example footprint. |
## State and action contract
Workflow resources live in the shared browser-session owner and initialize when received. Navigation and responsive layouts preserve accepted edits. Reload begins a fresh session for local workflows; an installed, unexpired [Source workspace](#document-docs-visitor-workspaces-md-49294a63218a) rehydrates its saved metadata. Drafts remain with their editors, with validation and refusal leaving them available for correction where specified. Theme preference uses its separate browser-local persistence. Access Grid’s **Reset scenario grants** restores all example grants and clears that grid’s draft while retaining the acting and inspected selections, accepted work and exploration. It is recovery of the public experiment, including in read-only scenarios; saving grants retains its authority checks. Compact desktop composition changes through CSS and preserves mounted editor content; the [layout contract](#document-docs-workspace-layout-md-b161445e3297) identifies the task-specific rail, disclosure and return owners.
Each command resolves the exact owned record, rechecks current authority and validates its supported transition or fields. Versioned editors also check the revision they opened. Recovery is domain-specific: resume/reopen, restore bundled metadata, restore an original release record, discard a proposal, or reopen/save a separate cohort definition. A successful permission preview alone never reports completed work.
Measured QC outcomes, recorded artifact acceptance and current review responses remain distinct. Source authority describes provenance; Access Grid grants describe user access. Map system examples and public release/source/artifact records use capability checks appropriate to their own records, without fabricating patient geography. Canonical specimen and Plate commands retain their consent/resource scope.
Profile's optional informational-toast preference affects actual local notices. Required feedback, errors, warnings and banners remain available. Unsupported preference controls have retired; intentional diagnostic previews identify their actual effect. The application keeps external refresh, file generation, release publication and remote delivery behind their explicit future execution boundaries.
## Language contract
- Operational guidance names the responsible actor or system, the work and its consequence. Current behavior leads; a future evaluation has its own receiving decision.
- Consent, privacy, legal and access restrictions retain their exact scope. Research explains its de-identified browser-session examples and states, “Re-identification is prohibited.” A recovery step offers permitted action rather than additional authority.
- Local acceptance names the actual result and lifetime. A review response, metadata proposal or rule definition does not claim laboratory execution, a generated file or a patient export.
- Historical wording, clinical facts, quotations and stable identifiers retain source fidelity. Any new clinical/legal conclusion requires its own evidence review.
- Empty or denied results explain the available recovery. Boolean NOT and executable assertions retain their logical meaning.
This register improves human inspectability. Future embedded AI needs its own grounded behavior evaluation before these records become an instruction or answer source.
## Evidence and next receivers
The initial all-view captures at 1024×768 and 1512×982 established composition pressure points. The [layout contract](#document-docs-workspace-layout-md-b161445e3297) connects bounded scrolling with compact Cohort/Artifact records, grouped Profile navigation, scene-preserving Plate rails and shared Light badges. Family browser checks cover draft retention, current identity, return focus, bounded records and readable label pairs. Settled captures support the visual comparison; they leave unexercised layouts to their receiving checks.
Owner tests distinguish exact-record acceptance from denied, stale or malformed commands. Focused production-browser journeys observe visible results, recovery, accepted source freshness, navigation and responsive retention. `available-actions.spec.mjs` checks the cross-view action surface; dedicated source, release, Map, QC, artifact, cohort and Profile specifications establish their deeper behavior. [The shared quality comparison](#source-b6f313adb223) provides explicit metric direction across specimen displays and cohort matching. Mobile keeps Corridor and Plate as its primary composition while exact-record companions read accepted local records.
[Local grant-experiment reset](#document-docs-permission-scenarios-md-cbea28e234a3) now restores example grants without restarting accepted work or exploration. The 64-entry saved-change boundary gives this recovery route while preserving an over-limit draft. [Compact composition](#document-docs-workspace-layout-md-b161445e3297) is delivered through the task-specific layouts above. [Disposable Source workspaces](#document-docs-visitor-workspaces-md-49294a63218a) now give metadata edits isolated, expiring persistence with history and reset. Verified identity remains a separate prerequisite for private/multi-user authority. [The input assessment](#document-docs-research-input-boundaries-md-c7dbe8e1d24d) follows the live forms through validation, safe rendering and stored-command boundaries. [Follow a sample](#document-docs-research-guided-exploration-md-ad62b036d202) now replays three working scenes with optional first-arrival invitation, scoped readiness and manual takeover. AI assistance retains its separate future design and acceptance decision.
## `docs/workspace-layout.md`
Source document: `docs/workspace-layout.md`.
# Workspace composition and return
Each desktop section keeps its primary task readable, supporting records reachable and accepted changes with their existing state owner. The common pattern is visible record identity, a bounded working area and an understandable return. Scene, rule, table and gallery tasks use different compositions to achieve it.
**Supersession:** Final-record and compiled-text containment remain in place. The current compact layouts resolve the later rail, action hierarchy and badge-contrast findings. The earlier recommendation to defer Cohort density and Plate rail work is replaced by the receiving patterns below.
## Choose the composition by task
| Task | Compact desktop composition | Wide composition and source owner |
| --- | --- | --- |
| **Find and inspect a source** | Search and type filters stay with the bounded collection; selected metadata and authority material have a wrapping reading viewport. | `SourcesView.tsx` retains the established collection/detail arrangement. [Source discovery](#document-docs-source-discovery-md-40a2d04884a2) owns edits and recovery. |
| **Build a cohort rule** | Below 1280px, one supporting rail switches between **Add cards** and **Rule & saved** beside the editor. Match, eligible and consent-held counts remain visible. Saving reveals the saved-rule receiver. | Both supporting rails remain visible from 1280px. `BooleanBuilderView.tsx` and `cohort-builder.css` own composition; the [compact-record contract](#document-docs-compact-records-md-8c3453ea976e) records the decision. |
| **Inspect an artifact** | Below 1280px, a selected gallery record uses the full working area. Its header keeps identity, revision and **Back to gallery** visible. Returning focuses the selected card. | The gallery and side inspector coexist from 1280px. `ArtifactsView.tsx` and `artifact-workspace.css` own placement. The comparison matrix retains its deliberate horizontal pan. |
| **Explore a permission scenario or preference** | Below 1280px, grouped Profile navigation moves above the content. The acting persona and environment stay visible while the Access Grid can inspect another person. | The grouped side rail returns from 1280px. `ProfileView.tsx` and `profile-layout.css` own geometry; [Profile preferences](#document-docs-profile-preferences-md-96585d17da7a) distinguishes scenario, personal and diagnostic controls. |
| **Read a sample's Plate history** | At 1024–1359px, **Sample histories** and **Sample details** open one local rail at a time over the stable scene. Close/Escape restores trigger focus; selecting a story reveals its result. The three-column result tray keeps its existing renderer. | Both rails sit beside the scene from 1360px. `LanesView.tsx` holds disclosure selection; `plate/PlateWorkspace.tsx` and `plate.css` own rendering, focus and this [Plate composition](#document-docs-plate-workspace-md-14d2cf5280a5). Below 1024px, the mobile workspace receives the same exploration intent. |
| **Read long lists or a graph** | Map's reference rail, Requirements, Decisions and Comparisons keep final records inside local scroll viewports while their summaries and filters remain reachable. | Their view components retain bounded record scrolling. Map keeps its intentional two-axis graph pan and lower artifact lineage strip. |
Specimens retains its [Cards/Table choice and topic-specific cell dialogs](#document-docs-specimen-table-md-cd6b2fe720d6). Presentations retains [brief-specific formats and pagination](#document-docs-presentation-styles-md-b2f82a4fd1a5). These are deliberate receiving patterns for comparison and reading, alongside the scene and editing compositions above.
## Shared behavior, local geometry
Desktop resizing changes these layouts through CSS. Cohort tools, the Artifact gallery and Plate rail content stay mounted while their compact alternatives are shown; Profile preserves its selected content across the desktop breakpoint. The current editing draft therefore survives the layout change. Explicit navigation away from an editor follows that editor's existing draft lifetime. Accepted records, permission scope, preferences and Plate selections remain with their shared session or exploration owners.
Each panel owns its scroll boundary. Wrapping records and compiled rule text use a shrinkable reading viewport; comparison tables and Map retain intentional horizontal or two-axis movement. `cohort-builder.css` and `artifact-workspace.css` scope Radix measurement-wrapper adjustments to their own reading viewports. A shared drawer would obscure useful context in some of these tasks, so the implementation shares state and theme contracts while keeping composition local.
`StatusBadge.tsx` and `record-badge.css` provide the shared badge treatment. Source/type/category, requirement, acceptance and release labels pair typed semantic ink with an opaque tint in Light mode. Existing geometry and Dark/High contrast paints remain intact. [Appearance modes](#document-docs-theme-contract-md-9253d68c555a) owns the palette and contrast evidence; labels continue to carry meaning independently of color.
The mobile [Corridor/Plate contract](#document-docs-mobile-showcase-md-a1c532f6fcd0), camera and scene motion, permission decisions, loading/source feedback and accepted workflow commands keep their existing owners. Layout choices expose those behaviors without adding another acceptance path.
## Receiving evidence and extension
- `workspace-scroll.spec.mjs` reaches the final Map reference, Requirement, Decision and Comparison, and the full Cohort expression, consent material and saved records. The compact Cohort receiver first reveals **Rule & saved**.
- `compact-records.spec.mjs` checks usable primary-area width, rail selection, saved-rule return, draft retention across desktop widths and Artifact return focus. Existing Cohort and Artifact journeys cover accepted commands, refusals and recovery.
- `profile-layout.spec.mjs` checks separated actor/inspection context, Access Grid reachability and draft/preference retention across the desktop breakpoint.
- `plate-workspace.spec.mjs` checks local rail entry/return, exclusivity, stable scene width, visible sample/source state and retained result selection across wide and mobile receivers. Existing Plate checks retain history loading, cache, late-response and command coverage.
- `record-badges.spec.mjs` measures rendered Light foreground/background pairs in Sources, Requirements and Artifacts, including selected cards. Focused before/after captures preserve the established Dark/High contrast treatment and badge geometry.
Settled 1024×768 and 1512×982 captures support visual comparison; the Plate family also checks its mobile boundary. These observations establish the named receiving states. Future sections can reuse a pattern when their task, state lifetime and return match it; a new common primitive follows a repeated need rather than a requirement to make every section identical. The [whole-view assessment](#document-docs-workspace-audit-md-c4b571428b60) records current operations and the next receiver. Return to the [repository guide](#document-readme-md-b33563055168) for development and deployment.
## `docs/workspace-storage.md`
Source document: `docs/workspace-storage.md`.
# Isolated visitor workspace storage
`server/workspaces` owns short-lived PostgreSQL persistence (with a retained MySQL compatibility adapter) for accepted Source metadata. A workspace keeps a visitor's title, summary and tags separate from the public catalog and from other visitors. The HTTP owner issues the opaque browser token; storage receives only its SHA-256 verifier, a random workspace identifier and the normalized owning origin. The actor recorded in an event is the selected showcase principal, role and environment; it represents the scenario used for acceptance.
This storage tranche provides the transaction boundary. The receiving API and client own cookie issuance, current scenario authorization, baseline source records, useful refusal feedback and the visible workspace lifecycle.
## Data and lifetime
`limits.mjs` owns a 24-hour absolute lifetime, 128 retained workspaces, 64 changed events per workspace, and 128 accepted-command receipts per workspace. Accepted no-ops have receipts so a later retry receives the same original outcome; they do not appear in changed-event history. Each new workspace admission removes at most 16 expired workspaces. Expired records stop being readable or editable immediately; physical cleanup occurs on subsequent admissions. Explicit removal deletes the workspace and cascades its projections and receipts in the same transaction.
The owning origin accompanies every lookup, edit, history read and removal. The returned workspace exposes its identifier, creation/expiry times and changed-event count. Token verifiers, origin bindings, command fingerprints and idempotency keys remain inside storage. Source provenance stays in the canonical bundled records; stored overrides contain only bounded metadata and a revision.
| Table | Ownership |
| --- | --- |
| `showcase_workspace_schema` | Separate migration version/signature and serialized workspace admission |
| `showcase_visitor_workspaces` | Token verifier, origin, absolute lifetime and bounded counters |
| `showcase_workspace_sources` | Workspace/source key, accepted metadata and revision |
| `showcase_workspace_receipts` | Scoped retry key, normalized command, simulated actor, server acceptance time, revisions and immutable result |
History is scoped to one source, defaults to 20 changed events and accepts a maximum of 64. Resulting revision orders that history even when two events share a timestamp. This is an inspectable showcase history with workspace expiry, rather than a permanent clinical audit record.
## Transaction contract
The selected adapter opens a short-lived connection per operation. Writes explicitly use **READ COMMITTED** so a request waiting for an ownership lock sees its predecessor's accepted receipt and the latest admission count. Reads use a consistent read-only snapshot. Connections have a two-second connect/lock limit and a four-second operation deadline; the owner closes the transport on timeout. A lost commit response is recovered through the original idempotency key.
Creation locks the singleton migration row before cleanup, count and insertion. Source commands lock the workspace before the source projection. Removal takes the same workspace lock, so it orders against accepted edits. A source transaction:
1. Resolves the token and owning origin, and checks absolute expiry.
2. Returns the original receipt for an identical retry; a changed fingerprint returns a conflict.
3. Compares the expected source revision. Missing overrides represent the canonical baseline at revision zero.
4. Invokes the caller's synchronous, current-policy transition against that locked projection.
5. Applies the projection, accepted event/receipt and counters atomically.
The API checks current authorization before retry lookup and in the transition. Refused transitions leave storage unchanged. The callback returns a bounded metadata projection; arbitrary properties and source provenance never enter the stored result. Same-key replay retains its original accepted record even after later edits.
## Explicit schema ownership
Use the [clone initializer](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277), or deliberately run `node --env-file-if-exists=.env scripts/database.mjs workspace-init` with the intended PostgreSQL setup role. Workspace setup is separate from catalog initialization and preserves existing catalog records. Ordinary build/start performs no DDL.
PostgreSQL setup owns one transaction, advisory lock, immutable schema checksum and physical-shape signature. Fresh setup commits all owned tables and its ready marker together. Repeated matching setup retains records. Foreign/partial tables, unsupported versions and changed constraints or indexes require inspection before repair. Future migrations retain released schema identities. [The PostgreSQL contract](#document-docs-postgresql-md-a7cc27814ec8) records this transaction and runtime-grant boundary.
The retained MySQL initializer has a separate signature and pending ownership marker because MySQL DDL can commit independently. Its optional proof preserves that compatibility behavior; public clone setup uses PostgreSQL.
`status()` distinguishes three receiving states: `stored` means the matching schema is available; `local` means all four tables are absent; `unavailable` means the connection or installed schema needs attention. An outage or partial migration therefore cannot silently redirect an accepted durable edit into browser-only state.
## Focused evidence
`node --test tests/workspace-storage.test.mjs` covers shared input admission and the retained MySQL connection boundary. [PostgreSQL engine and HTTP checks](#document-docs-postgresql-md-a7cc27814ec8) exercise atomic setup, catalog preservation, current revision/permission checks, concurrent stale writes and quota admission, exact retries, rollback, expiry, removal and indexed reads. The [container proof](#document-docs-runbooks-local-postgresql-clone-md-5708104f1277) adds actual process restart and trusted backup recovery using the original browser workspace.
For a change to MySQL compatibility, `npm run test:mysql` deliberately exercises that adapter on an independently provisioned disposable loopback database. Ordinary unit checks and PostgreSQL proof each retain their own population; one passing adapter is not evidence that the other ran.
## `guidelines/Guidelines.md`
Source document: `guidelines/Guidelines.md`.
**Add your own guidelines here**
## Repository source references
These are authored repository references outside the bundled Markdown population. They are source coordinates, not public application routes or copies of those files.
- Repository reference: `.betterleaks.toml`
- Repository reference: `.figma/make`
- Repository reference: `.figma/make/site.json`
- Repository reference: `.github/actions/prepare/action.yml`
- Repository reference: `.github/rulesets/README.md`
- Repository reference: `.github/workflows`
- Repository reference: `.github/workflows/browser-checks.yml`
- Repository reference: `.github/workflows/core-checks.yml`
- Repository reference: `.github/workflows/database-proof.yml`
- Repository reference: `.github/workflows/documentation-deploy.yml`
- Repository reference: `.github/workflows/documentation-preflight.yml`
- Repository reference: `.github/workflows/postgresql-proof.yml`
- Repository reference: `.github/workflows/publication-scan.yml`
- Repository reference: `.github/workflows/verify-change.yml`
- Repository reference: `.mise.toml`
- Repository reference: `Dockerfile`
- Repository reference: `LICENSES/shadcn-ui.txt`
- Repository reference: `docs/content-manifest.json`
- Repository reference: `docs/images/readme/`
- Repository reference: `docs/images/readme/desktop-cohort-builder.png`
- Repository reference: `docs/images/readme/desktop-corridor.png`
- Repository reference: `docs/images/readme/desktop-sample-history.png`
- Repository reference: `package.json`
- Repository reference: `playwright.config.mjs`
- Repository reference: `pnpm-lock.yaml`
- Repository reference: `public/source-of-truth-systems-social-preview.png`
- Repository reference: `scripts`
- Repository reference: `scripts/clone/initialize.mjs`
- Repository reference: `scripts/documentation/release.mjs`
- Repository reference: `scripts/prove-database.mjs`
- Repository reference: `scripts/security/install-betterleaks.mjs`
- Repository reference: `scripts/security/scan-secret-material.mjs`
- Repository reference: `scripts/serve.mjs`
- Repository reference: `server/README.md`
- Repository reference: `server/data/connection.mjs`
- Repository reference: `server/data/postgres-schema.sql`
- Repository reference: `server/data/prepare-catalog-seed.mjs`
- Repository reference: `server/data/schema.sql`
- Repository reference: `server/data/scoped-repository.mjs`
- Repository reference: `server/graphql`
- Repository reference: `server/graphql/api.mjs`
- Repository reference: `server/security/request-admission.mjs`
- Repository reference: `server/workspaces`
- Repository reference: `server/workspaces/connection.mjs`
- Repository reference: `server/workspaces/graphql.mjs`
- Repository reference: `server/workspaces/store.mjs`
- Repository reference: `shared/README.md`
- Repository reference: `shared/permission-scope.mjs`
- Repository reference: `shared/plate-records.mjs`
- Repository reference: `src/app/README.md`
- Repository reference: `src/app/components/ShowcaseCredit.tsx`
- Repository reference: `src/app/components/SourceMetadataEditor.tsx`
- Repository reference: `src/app/components/guide/GuideProvider.tsx`
- Repository reference: `src/app/components/guide/guideState.ts`
- Repository reference: `src/app/components/guide/useGuideScene.ts`
- Repository reference: `src/app/components/plate/plateCommands.ts`
- Repository reference: `src/app/components/plate/sceneTransition.ts`
- Repository reference: `src/app/components/ui/scroll-area.tsx`
- Repository reference: `src/app/components/ui/utils.ts`
- Repository reference: `src/app/components/views/SourcesView.tsx`
- Repository reference: `src/app/data/index.ts`
- Repository reference: `src/app/data/wellResults.ts`
- Repository reference: `src/app/services`
- Repository reference: `src/app/services/accessService.ts`
- Repository reference: `src/app/services/exploration/ExplorationProvider.tsx`
- Repository reference: `src/app/services/permissionScenario.tsx`
- Repository reference: `src/app/services/plateHistory/cache.ts`
- Repository reference: `src/app/services/sourceSession.ts`
- Repository reference: `src/app/services/sourceWorkspace.ts`
- Repository reference: `src/app/services/specimenQuality.ts`
- Repository reference: `src/app/services/writeGate.ts`
- Repository reference: `src/server/example-data.ts`
- Repository reference: `src/styles/fonts.css`
- Repository reference: `src/styles/tailwind.css`
- Repository reference: `tests`
- Repository reference: `tests/README.md`
- Repository reference: `tests/browser`
- Repository reference: `tests/browser/corridor-camera.spec.mjs`
- Repository reference: `tests/browser/guided-exploration.spec.mjs`
- Repository reference: `tests/browser/permission-scenario.spec.mjs`
- Repository reference: `tests/browser/permission-scope-scenes.spec.mjs`
- Repository reference: `tests/browser/plate-commands.spec.mjs`
- Repository reference: `tests/browser/responsive-exploration.spec.mjs`
- Repository reference: `tests/browser/responsive-session.spec.mjs`
- Repository reference: `tests/browser/source-operations.spec.mjs`
- Repository reference: `tests/browser/source-workspace.spec.mjs`
- Repository reference: `tests/database-connection.test.mjs`
- Repository reference: `tests/deployment.test.mjs`
- Repository reference: `tests/document-policy.test.mjs`
- Repository reference: `tests/documentation-release.test.mjs`
- Repository reference: `tests/graphql.test.mjs`
- Repository reference: `tests/guided-exploration.test.mjs`
- Repository reference: `tests/mysql-workspaces.mjs`
- Repository reference: `tests/permission-policy.test.mjs`
- Repository reference: `tests/plate-commands.test.mjs`
- Repository reference: `tests/plate-history-client.test.mjs`
- Repository reference: `tests/postgres-workspaces.mjs`
- Repository reference: `tests/request-admission.test.mjs`
- Repository reference: `tests/scene-transition.test.mjs`
- Repository reference: `tests/scoped-client.test.mjs`
- Repository reference: `tests/scoped-reads.test.mjs`
- Repository reference: `tests/server-fixture.mjs`
- Repository reference: `tests/source-session.test.mjs`
- Repository reference: `tests/source-workspace.test.mjs`
- Repository reference: `tests/startup-bundle.test.mjs`
- Repository reference: `tests/workspace-api.test.mjs`
- Repository reference: `tests/workspace-storage.test.mjs`
- Repository reference: `vite.config.ts`
- Repository reference: `vite.figma.config.ts`