I started thinking about this after discussing the idea with a mate who works in pharma. As the author of CellScript, I kept coming back to one moment: a batch becomes released, based on records that several people and organizations have contributed. What exactly did the reviewer approve, and could another participant check that decision without asking the original application for its verdict?
Lineage is my attempt to work through that question in running software. It follows a batch from registration through evidence collection, quality review, release, and a later correction. Source files are retained, declarations and decisions are signed, and an exported package can be verified on another machine. CellScript executes the release predicate locally in CKB-VM.
The screenshots come from a real acceptance run. The people, organizations, samples, and reports are explicitly synthetic. The document hashes, signatures, compiler execution, and failures are real. A fresh installation starts empty.
Biologics include therapeutic proteins, vaccines, and living-cell products. They are not all personalized medicines. In an autologous cell therapy, however, the starting cells come from the same patient who will receive the treatment. An allogeneic treatment starts with donor cells, which introduces different relationships between source material, batches, and recipients. The FDA's biologics introduction and CAR-T guidance helped me understand why identity needs attention at every handoff.
I keep three questions separate. Chain of identity asks whose material and intended treatment these records concern. Chain of custody asks who had the material. Handling records address conditions such as temperature. A valid shipment signature cannot establish that the sample was labelled correctly at collection. My application currently binds a batch to a sample reference; it does not establish the physical identity chain or trace bedside administration.
A CDMO is a contract development and manufacturing organization. It may manufacture for a sponsor while an outside laboratory performs some testing. Their records can live in several systems:
| Term | What it means in this discussion |
|---|---|
| MES | Manufacturing execution system, recording production activity |
| EBR | Electronic batch record, describing how a particular batch was made |
| LIMS | Laboratory information management system, handling samples and results |
| QMS | Quality management system, including investigations, changes, and approvals |
| ERP | Enterprise resource planning system, including material and inventory references |
Those are possible sources, not a required architecture. I do not assume these systems are broken, or that everyone works through email. Existing platforms such as TrakCel already coordinate therapy journeys. I want to understand what still costs effort when a decision crosses organizational boundaries: reconciling identities, resolving report versions, retrieving the evidence, or establishing who approved which set of records.
GMP, good manufacturing practice, concerns the controls around consistent manufacture and quality. The FDA uses CGMP to emphasize current practices. Finished-product testing does not replace those controls. QC concerns testing and assessment; QA concerns the wider quality system and its decisions. A QP, Qualified Person, has a specific certification responsibility in the EU. An application permission called quality does not establish that professional or legal authority. The FDA GMP overview and EMA GMP questions and answers give the wider context.
That is why I separate readiness from authorization. Passing the encoded checks makes a batch ready for review. An accountable person still has to assess the source records and approve the particular evidence set.
A quality owner approves a versioned policy before registering batches against it. Laboratory and manufacturing members upload original documents and sign assessments. The policy chooses from six categories:
| Category | Intended question | Issuer role in Lineage |
|---|---|---|
| Identity | Does the assessment support the expected material identity? | Laboratory |
| Potency | What assessment supports biological activity? | Laboratory |
| Sterility | What testing and assessment support the sterility requirement? | Laboratory |
| Viability | What assessment supports the living-cell requirement? | Laboratory |
| Manufacturing record | What supports the assessment of this batch's manufacture? | Manufacturer |
| Deviation disposition | How were recorded departures assessed for this decision? | Manufacturer |
This is a deliberately small application vocabulary, not a universal release specification. Potency and viability are different attributes. Lineage checks attributable declarations and exact source bytes; it does not calculate scientific acceptance limits or infer clinical efficacy. A deviation-disposition upload cannot establish that nobody omitted an investigation from the source QMS.
Each declaration binds its document hash, batch, sample, process, policy, category, result, method, assessment, and issuer. A category has one active record. Replacing it requires an explicit revocation. The release binds the complete active manifest, policy, revision, approval meaning, approver, and execution receipt.
I also find the process-version question interesting. CMC means chemistry, manufacturing, and controls. Changing a process, material, site, or method can require an assessment of the resulting product. Comparability is that scientific assessment, not equality between document hashes. ICH Q5E describes relevant principles. Today a batch carries a fixed process-version string and policy. A governed graph connecting changes, comparability packages, and their approvals is still ahead.
The phrase “shared truth” needs care here. Cryptography can preserve an attributable claim and detect changed bytes. It cannot establish that a specimen was collected correctly or that every relevant record was submitted. The FDA data-integrity guidance concerns a much wider responsibility than keeping a hash.
These captures follow AT-2026-0104. Click a stage to see its screenshot. Desktop captures use a 1440 × 1000 viewport, with full-page captures where the record is longer; mobile uses 390 × 844. Four additional synthetic queue records are created through the authenticated API for search and queue checks. None enter the normal workspace.
01 — Start with an empty workspace
The owner creates the workspace and their quality account. A fresh installation has no preset credentials or records. This capture is taken before credentials are entered.
02 — Approve the requirements first
The policy fixes the process version and required evidence categories. A batch registered against this policy retains that version when later policies are added.
03 — Assign responsibility
Quality, laboratory, and manufacturing members have separate accounts and signing identities. These are application permissions; they do not establish professional credentials. Keys are held encrypted by the workspace server.
04 — Register the batch
AT-2026-0104 is bound to SAMPLE-0104 and the approved policy. This form records the application's batch/sample relationship; it does not perform a physical identity check.
05 — Missing evidence blocks readiness
The batch begins with six unmet requirements. Release authorization is unavailable, and server-side checks also reject incomplete evidence.
06 — Upload the source record
The laboratory member uploads a real file and records an assessment and procedure reference. Signing binds the exact document bytes and declaration to this batch. The text file explicitly identifies itself as a synthetic acceptance record.
07 — Laboratory work alone is insufficient
Identity, potency, sterility, and viability declarations are present. Manufacturing and deviation records are still outstanding. The laboratory account cannot authorize release.
08 — Ready for quality review
The manufacturing member has added the remaining declarations. All six required records pass integrity and attribution checks. The batch still needs a quality decision.
09 — Approve this evidence set
The reviewer confirms the approval meaning and authenticates again. The password field is empty in this capture. Approval invokes actual local CellScript execution before a decision can be recorded.
10 — Record the release
The signed decision binds the evidence manifest, policy, revision, approver, and VM execution receipt. This is a local release record, with no claim of CKB network confirmation.
11 — Export and verify
The browser downloads the evidence package and public trust directory using the application's download controls. The same files pass the standalone CLI verifier and browser verification with the browser network disconnected. Files never leave the browser during verification. In this test both files come from a known local workspace; another organization would need to establish trust in the key directory separately.
12 — Altered bytes fail verification
The test changes a source document in a copy of the exported package. The verifier rejects that copy. The original workspace records are unchanged.
13 — Review the queue
The register shows one released batch, three collecting evidence, and one held batch. Counts are calculated from those records. Search and clearing the search are exercised in the same run.
14 — Inspect the mobile layout
The same queue at a 390-pixel viewport. Navigation becomes a drawer, while the batch table has its own horizontal scroll area. The acceptance test checks that the page itself does not overflow horizontally.
15 — Withdraw evidence after release
The quality member records why the identity evidence is being revoked. Revocation preserves the original bytes and declaration.
16 — The batch is held
With a release record now depending on revoked evidence, the current batch enters a hold. Its previous authorization remains in history. A fresh release is blocked.
17 — Resolving a hold does not restore release
The quality member records a resolution permitting corrected evidence collection. The batch returns to collection with the identity requirement outstanding.
18 — Correct the evidence and authorize again
The laboratory submits revision 2 of the synthetic identity report. Quality reviews and authorizes again through the real compiler path. The test asserts that the new evidence manifest differs from the original. The revoked record is expanded below the current evidence set.
19 — Reconstruct the decisions
Batch history retains the original collection, first release, revocation, hold resolution, replacement, and second release. The current release pointer does not erase the earlier approval.
20 — Inspect the workspace audit trail
Signed events link changes across the workspace. This is a local event chain; an operator controlling the database and signing keys remains a trust authority. The retained exports and separately held checkpoints matter.
The correction is the part I most wanted to get right. Revoking evidence used in a release puts the batch on hold. Resolving that hold returns it to collection; it does not restore the old release. A laboratory supplies the replacement, quality reviews again, and a second decision binds a different manifest. The original approval remains reconstructable.
The application validates evidence and supplies integer facts to contracts/release.cell. For each approval it creates a temporary, dependency-free package, locks it, and executes cellc test --backend ckb-vm --frozen --json. The predicate checks evidence masks, hold state, and revision equality. Failed compilation, failed execution, missing tooling, or an incomplete receipt blocks release. The application rechecks the batch after the asynchronous run and verifies that the receipt matches the facts being committed.
This is a local signed ledger with local CKB-VM execution. No CKB transaction is submitted. The VM receives application-supplied facts; it does not independently authenticate files, laboratory identities, physical material, or transaction inputs. The compiler may optimize the predicate over these bound facts. This exercise establishes the local execution path, not an independent consensus trust boundary.
CKB's Cell replacement and Type Script model remains a plausible next boundary. A real on-chain implementation needs governed batch issuance, transaction-bound evidence and policies, live revocation state, and adversarial creation/update tests. A lineage diagram or a local VM receipt does not implement those things.
The server holds members' encrypted private signing keys. It is a custodial workspace, not independent institutional key custody. Someone controlling the database and master key remains a trust authority. Retained exports and externally held event checkpoints help detect replacement of history; they cannot make that operator disappear.
I would first sit down with someone who reviews release evidence and work through a de-identified packet. Which checks repeat? Which discrepancies take time? Which decisions require scientific judgment? My discussion with my mate prompted this experiment; it was not industry validation. Signed packages may already be useful without shared chain state. I want evidence for the extra trust boundary before expanding the system around it.
Requires Node 22.13 or newer; the tested version is recorded in .nvmrc. The installer supports Linux and macOS on x64 and arm64 and requires curl and tar.
git clone https://github.com/CellScript-Labs/lineage.git
cd lineage
npm ci
npm run compiler:install
npm run build
npm startOpen http://127.0.0.1:4310 and create the first workspace account locally. It becomes the quality owner. There are no seeded records, preset accounts, or automatic successful responses. Add laboratory and manufacturing accounts, approve a policy, and register a batch to begin. A user's sidebar account control supports password changes and invalidates other sessions.
compiler:install downloads official CellScript 0.31.0, verifies a platform-specific SHA-256 pinned in the installer, and installs .tools/cellc. It does not change the sibling compiler repository. CELLC_PATH overrides that path. A developer checkout can also use ../CellScript/target/debug/cellc when the pinned local installation is absent. Missing compiler support blocks release while leaving evidence collection usable.
For frontend development, run npm run dev and open http://127.0.0.1:5173. Vite proxies API requests to port 4310. npm start serves the built frontend and API together.
npm run verify -- batch-evidence.json lineage-trust.jsonThe CLI exits nonzero if verification fails. The browser uses the same verification module and Web Crypto for SHA-256 and Ed25519, without uploading either file. Browser verification requires HTTPS or localhost and Ed25519 support. A browser still loads its verifier code from the application; use an independently obtained checkout and the CLI when that application operator is outside your trust boundary.
The verifier checks original bytes, issuer roles, signatures, policy bindings, event continuity, all retained release manifests, and their recorded VM inputs. It reconstructs the batch's state and revision from signed events, including revocations and holds. A new exporter signature alone cannot rewrite that separately signed history. It checks receipts as records and does not rerun the VM.
Establish trust in the public-key directory through a separate channel. The export commits a particular directory version, so retain that matching version. A verified package is a snapshot, not proof that no later correction exists. Missing records in an external source system remain outside this verifier's knowledge.
React and TypeScript provide the interface. Express serves the API. SQLite stores the workspace, original document bytes, signed declarations, policies, sessions, and events. Persisted batch states are collecting, held, and released; readiness is computed from the current evidence. State changes and their signed events commit in one transaction. Database triggers reject edits or deletions of audit events.
| Variable | Default or requirement |
|---|---|
HOST |
127.0.0.1 |
PORT |
4310 |
DATA_DIR |
.data under the project |
CELLC_PATH |
.tools/cellc, then the sibling development binary |
APP_ORIGIN |
Development defaults to http://127.0.0.1:5173; production requires the exact public HTTPS origin, without a trailing slash |
COOKIE_SECURE |
Production requires true |
NODE_ENV |
Set production for production startup validation |
deploy/lineage.service is a Linux systemd unit for /opt/lineage, running as the dedicated lineage user. It retains state in /var/lib/lineage, uses the installed compiler, restricts filesystem writes, and reads /etc/lineage.env for APP_ORIGIN. Install Node at /usr/bin/node, create that service account, build and install the app at /opt/lineage, configure the environment file for the actual public origin, and put the loopback backend behind an HTTPS reverse proxy. The unit uses secure cookies; complete initial account setup through that configured origin before giving others access. The first setup claims the workspace.
GET /healthz checks database access without exposing workspace details. API responses are not cached. Mutation requests require session-specific CSRF tokens, with browser-origin checks. Authentication, password confirmation, and release routes are rate limited. At most two release compiler jobs run concurrently per process. The service does not trust forwarded client addresses; configure rate limits at the reverse proxy as well.
Passwords use scrypt with random salts. Random session tokens are stored as hashes and expire after eight hours. Account suspension invalidates active sessions. Ed25519 private keys are encrypted with AES-256-GCM under a locally generated master key. The data directory is private, and key/database permissions are restricted. Startup refuses an existing database whose key is missing or malformed, and refuses newer schema versions.
Back up the entire data directory while the service is stopped, including the database, WAL files if present, and master key. Keep the backup encrypted and rehearse restoration into an isolated directory. Preserve an independent public trust directory and retained event checkpoints. Losing the master key prevents further signing with those identities; silently creating a replacement would not recover them.
Each source document is limited to 5 MB. Browser package verification accepts up to 64 MB; use the CLI for larger exports. Every workspace member can inspect and export the workspace's records. This is a single-workspace, single-process deployment; it has no record-level tenant isolation, distributed availability, institutional identity federation, or external signing hardware integration.
There are no MES/LIMS/QMS connectors, automated recall graph, bedside identity checks, comparability workflow, or deployed Type Script hidden behind the interface. Those are unimplemented extensions. The current release workflow is functional, but the software has not undergone regulated computerized-system validation or GMP qualification. A real clinical deployment requires product-specific requirements, qualified identities, scientific review, and an approved operating process.
npm run checkThis runs formatting, domain/HTTP/storage regressions, the production build, the real compiler predicate checks, and the full browser workflow. Install Chromium once with npx playwright install chromium. The supplied GitHub Actions configuration installs Chromium's system dependencies as well and uses the checksum-pinned official compiler. Focused commands are npm test, npm run build, npm run format:check, npm run test:contract, and npm run test:browser.
The optional Actions configuration is ci/github-actions.yml. To enable automatic checks, move it to .github/workflows/check.yml and push with credentials permitted to manage workflows. It is supplied inactive; local verification does not imply a successful remote CI run.
Unit tests use a clearly labelled VM receipt fixture to isolate domain rules. The contract suite runs the actual compiler for one accepted case and six rejected cases. The browser suite uses the actual compiler for both release decisions, exercises downloads and the standalone CLI, disconnects the browser network for valid/tampered package verification, and captures the 20 stages above. It also checks runtime errors, mobile page overflow, and axe WCAG 2 A/AA and 2.1 AA findings on the batch register. That is focused coverage rather than a complete accessibility audit.
Browser data lives in a temporary database and is removed on shutdown. Screenshot timestamps, signatures, and identifiers change on each run. The screenshots are test artifacts, not records preloaded into the normal application. Seven additional -view.png files are direct viewport captures suitable for a forum post. Upload the images to the forum and use its resulting image references when posting this README outside GitHub.
Keep this repository independent of the CellScript compiler. Preserve source bytes, signatures, historical decisions, and revocations. Keep release enforcement on the server, recheck state after asynchronous execution, and commit decisions atomically with their events. Do not add success fallbacks, sample records to normal startup, or UI claims of chain confirmation. Never commit .data, .tools, credentials, session tokens, or private keys. The verifier must continue working from supplied bytes and separately trusted public keys without server access. This README is the single maintained Markdown document.