insanely great

Reference Architecture · v0.9.5

Domain-AdaptiveManufacturing

Software that builds and configures itself to the reality of the manufacturer — from a two-person startup to Nestlé and Apple — without converging on the lowest common denominator, and without becoming a thousand unmaintainable bespoke codebases.

C · Bespoke surfaceGenerated experience + customer logic — unique per tenant
B · Adaptation engineComposes & configures validated blocks — shared engine, per-tenant output
A · Invariant substrateOntology · fact ledger · data fabric · governance — shared, trusted, fixed
determinism below · cognition above
Control layerPLC · motion · robot · safety — deterministic, real-time, certified
Document
Reference Architecture
Status
For discussion
Audience
Platform architects & eng leaders
Published via
insanely great

01  ·  The reframe

Standardize the physics. Bespoke the experience.

Traditional manufacturing SaaS — an MES bolted to an ERP — fails not because it shares a core, but because it draws the abstraction line backwards.

It standardizes the workflows, screens, and logic — the things that genuinely differ between companies and should be bespoke. And it leaves the primitives rigid and implicit — material, lot, operation, genealogy, measurement — the things that are actually universal and should be bedrock.

The result has weak opinions about physics and strong opinions about your daily routine. So the real process migrates into spreadsheets and tribal knowledge that live around the system, and the system of record becomes a fiction maintained for auditors.

Be uncompromising about the invariant. Hold zero opinion about the variable.

The agentic era makes this affordable, because the cost that forced one-size-fits-all — human dev-years per customer — is collapsing. Build-once-sell-many only mattered when building cost human-years.

02  ·  Design tenets

Seven decisions everything follows from.

01

Strong opinions on the invariant; none on the variable

The whole architecture falls out of where this line is drawn.

02

Determinism below, cognition above

Real-time safety-bearing control stays deterministic. Agents live above a governed, audited, human-gated contract. No agent in the interlock path — ever.

03

Immutable truth, bespoke interpretation

One canonical, append-oriented fact ledger; many bespoke projections and logics computed over it.

04

Bespoke by composition, not by codegen

Adaptation composes and configures validated blocks. True code generation is the gated exception — so bespoke fit never becomes a forever liability.

05

Open-world ontology

A customer can add concepts the core doesn't know without forking the core.

06

The reality is the spec — continuously

Onboarding is never one-time. The platform re-adapts as plant, products, and regulations change. No replatforming cliff.

07

Generation is trusted only through governance

Every adaptive artifact is versioned, validated against tests and golden checks, signed, and auditable. You validate the generator and the envelope — not just each output.

03  ·  The three strata

Trusted where reality is common. Bespoke where it differs.

A · Substrate

Shared, trusted, fixed

Universal ontology (open-world). The immutable, event-sourced fact ledger. The data fabric mapping historian, MES, ERP, ATE, LIMS, supplier portals into the ontology. The control boundary. Governance & audit.

B · Engine

Shared engine, per-tenant output

A capability library of validated, domain-blind blocks. The agentic onboarding that induces a tenant's ontology and profile and composes what fits. A gated generation envelope. Continuous re-adaptation.

C · Surface

Unique per tenant

The generated experience — UIs, operator screens, dashboards, work instructions in the customer's vocabulary. The customer's own logic & decisions: scheduling rules, dispositions, escalation paths, definitions of good.

Two layers authored once. Two induced per tenant. One derived.

The kernel and the regulatory packs are written once and reused. The ontology mapping and adapters are induced or configured per tenant. The defaults are derived from archetype × risk. No layer requires a code fork per customer — which is what keeps "adapt to anyone" a product rather than a consultancy.

And it demotes your ERP: in the data fabric, SAP and the historian and the MES become sources and sinks among others, not the tyrants whose schema you must obey. The semantic center of gravity moves to the platform's open, customer-fit ontology. Run it over what you have; migrate authority into the ledger on your terms.

04  ·  One platform, every scale

A startup isn't running a lite version. It's running the same platform.

The architecture doesn't change across scale — only the tenant profile, the scale envelope, and the governance intensity do.

Startup

Sources
spreadsheets, a few machines, no historian
What the engine composes
a lightweight system from a few blocks
Governance
light
Substrate · blocks · engine
identical

Nestlé / Apple

Sources
thousands of sources, deep ERP, full OT stack
What the engine composes
the same blocks, at scale, heavily governed
Governance
regulated, audited, signed, validated
Substrate · blocks · engine
identical

The startup grows continuously into the enterprise shape instead of hitting the traumatic replatforming cliff — the "rip out the spreadsheets and survive an 18-month SAP implementation" rite of passage. Removing that cliff is, by itself, a serious value proposition.

05  ·  The conformance / alignment layer

Born aligned. Not validated after the fact.

Borrow the practice teachers use to align lesson plans to a standards framework, and apply it to manufacturing's governing specs: make the spec a structured target, bind every system part to it, and prove the binding with evidence drawn from the fact ledger.

Spec-as-data. An IATF clause, an AS9100 requirement, a 21 CFR control, a HACCP critical control point, a control-plan line, a GD&T callout — each decomposes into atomic requirement nodes with stable IDs, bindingness, and revision. The manufacturing analog of an addressable standard.

Conformance bindings. Every part — a capability block, a control limit, a workflow, a generated screen — declares which nodes it satisfies. Bidirectional: node → implementing parts (coverage), part → nodes served (justification). Orphans and gaps fall out automatically.

Evidence, and a live posture. A tag is a claim; evidence is proof. Each binding links to design-time evidence and to runtime results streamed from the ledger — and carries live state: satisfied / at-risk / failing. Compliance posture is just another projection over immutable truth. No binder is assembled before an audit; the posture is always current.

One thread, end to end

A turned shaft diameter, monitored by a single SPC control limit that simultaneously discharges a drawing tolerance and an IATF clause.

DRW:4471-A/rev-C/char-07
Ø12.000 ±0.025 mm · Key Product Characteristic
shall
IATF16949/9.1.1.1
SPC & demonstrated capability for special characteristics
shall
CTRLPLAN:line-14
Control-plan row (crosswalk)
shall
SPC:contract/turning-op-30/char-07
X̄-R limits · Cpk ≥ 1.33
design-time · registry · signed

Phase-I study · ARL calibration · gage R&R · Cpk study

runtime · fact ledger · live

measurement events · control state · rolling Cpk · gage calibration

live posture
Live conformance posture
satisfiedat-riskfailing

A projection over the fact ledger — rendered to both the audit view and the engineer's process view from the same underlying facts.

A control signal, a capability drop, or an out-of-cal gage flips the posture — and the flip lights up against both the drawing node and the IATF clause at once, because both are computed from the same ledger facts. The auditor's compliance view and the engineer's process view are one truth rendered twice.

And because bindings are live and bidirectional, a spec change — a drawing rev C → rev D tightening the tolerance — emits a precise re-validation worklist: exactly the one affected part, nothing more. Continuous adaptation produces a scoped delta instead of a full re-validation.

06  ·  The representation layer

GitOps for the factory.

Every human gate, every conformance review, the anti-lock-in promise, and agent-editability all require the bespoke surface to be legible, diffable, signable text. You cannot meaningfully gate what you cannot read.

ArtifactRepresentationWhy
Tenant profile, ontology, contracts, bindings, defaults
structured config
YAML as the editing skin over a strict schema; a typed config language (CUE / Dhall / KCL) where correctness is criticalhuman-diffable; the schema kills YAML's ambiguity footguns
Work instructions, SOPs, requirement statements, rationale
prose + metadata
Markdown + frontmatter — the SKILL.md patternone file: machine reads the header, human reads the body, the two can't drift
Scheduling logic, dispositions, alarms, envelopes
behavior
a small, constrained, sandboxed DSL with a real grammarlogic-in-YAML becomes the unmaintainable nested monster CI grew into
The fact ledger
truth
event store — not config at alldeclarative config and immutable events must stay strictly separate

If the entire bespoke surface is human-readable text under version control, the governance machinery is simply modern software practice: the human gate is a pull-request review; the validation envelope is CI — schema validation, golden checks, and the born-aligned conformance check; the audit trail is commit history; signing is your commit-signing policy; rollback is a revert; and the re-validation worklist is a CI job triggered when a requirement node changes.

The whole trust model falls out for free once customization is reviewed, validated, signed text.

07  ·  The control & automation layer

Lights-out isn't ungoverned. It's governance, front-loaded.

The platform is prepared by design to supervise and orchestrate the automation layer — and explicitly not to be the control or safety layer. Lights-out is the case that proves the boundary must be absolute.

L4 — ERP / business
L3 — MES / operationsplatform cognition · probabilistic · supervisory
L2 — SCADA / supervisorydispatch jobs · select & download recipes / robot programs · detect faults
governed · audited · human-gated contract
L1 — PLC · motion · robot · SAFETYdeterministic · hard-real-time · certified — IEC 61508/62061 · ISO 13849 · ISO 10218 / TS 15066
L0 — sensors / actuatorsthe platform observes & commands — never is — this layer

Any platform-initiated physical action passes through a governed actuation contract — itself a representation-layer artifact: human-readable, schema-validated, signed.

actuation_contract: id: cell-7/load-and-run authority_level: supervisory # never "safety" target: { resource: robot-cell-7, action: run_program } allowed: programs: [PGM-4471-rough, PGM-4471-finish] # whitelist, not arbitrary setpoints: spindle_rpm: { min: 800, max: 2400 } # hard clamps rate_limit: 1/min preconditions: # all must hold, checked locally - interlocks_satisfied: true - gage.calibration: in_date # a conformance binding - operational_envelope: cell-7/turning on_violation: reject_and_hold # deterministic local guardian audit: signed binds: [IATF16949/9.1.1.1, SOP/cell-7-startup] # conformance

The guardian that enforces on_violation lives at the certified layer, not in the platform — an out-of-envelope command is physically rejected regardless of what the cognition believes. And the human gate doesn't disappear at 3 a.m.; it relocates to design time. A human already approved exactly what the cell may do; at runtime it executes autonomously inside that pre-approved envelope.

operational_envelope: id: cell-7/turning ratified_by: j.smith (Mfg Eng) # design-time human gate valid_when: # the operational design domain material: [4140-steel] part_numbers: [4471-A/rev-D] shift: any # lights-out permitted autonomy: act_within_envelope # run unattended inside the domain on_edge: excursion_minor: { action: adjust_within_clamps, log: true } excursion_major: { action: safe_hold, quarantine_wip: true, page: oncall-remote } outside_domain: { action: safe_hold, page: oncall-remote } # never improvise twin_validated: true # simulated before deploy

The runtime's intelligence is boundary detection and safe degradation — recognize you're outside the validated domain, fail to a safe state, quarantine the WIP, page a remote human — never improvisation in a novel situation. Because lights-out removes the human who'd catch a bad config, "validate before deploy" for physical actuation means simulate against a digital twin first, not merely schema-check.

The representation layer is what makes the control layer safe to automate.

08  ·  The missing primitive

Authority is bedrock, not a setting.

The reframe named the universal primitives — material, lot, operation, genealogy, measurement. There is one more the architecture has been quietly assuming on every page: who is allowed to do what. Every ratified_by, every signed commit, every disposition, every release-under-deviation, every human gate resolves against an authority graph that was never drawn.

Left implicit, authority is the weakest link in the chain of trust: a gate is only as strong as the identity behind the signature, and a signature with no governed graph behind it proves nothing. So authority earns the same bedrock treatment as the fact ledger — a governed, event-sourced primitive in Stratum A, not a per-tenant access-control afterthought bolted to the surface. And the thesis applies to it exactly as it applies to everything else.

Standardize

The shape of authority

Principals, roles, grants, scopes, delegation, revocation, expiry — and one fixed grammar: X may do Y within scope Z, granted by W, until T. Identical from a three-person startup to a fifty-thousand-person enterprise.

Bespoke

Who holds it, what roles mean

Every org's titles, hierarchy, and disposition rules differ. Induced per tenant and fed from the HR system like any other source. The platform holds zero opinion about your org chart.

Gate

The assignments themselves

Who may disposition a nonconformance, release under deviation, ratify an envelope, sign a generated block — the unsafe-to-guess decisions. The agent proposes and routes; it never grants. Granting is itself a human-gated, signed act.

authority_grant: id: grant/mrb-disposition-line-14 principal: a.reyes # who role: mrb-disposition-authority # what it means — tenant-defined scope: # where it applies site: jax-1 operations: [op-30-turning] characteristics: [char-07] may: # verbs from a fixed grammar - disposition_nonconformance - release_under_deviation: { max_qty: 50 } # bounded, like actuation clamps granted_by: m.okafor (Quality Director) # design-time human gate valid_until: 2026-12-31 # expiry, never forever binds: [IATF16949/8.7, SOP/mrb-line-14] # conformance exercise: logged_to_ledger # every use is an immutable event on_revoke: recompute_posture # a lapse flips conformance live

It threads the conformance layer with no new machinery. A clause like "special characteristics dispositioned only by qualified personnel" becomes a binding from a requirement node to an authority grant — and authority carries the same live posture as everything else. A revoked role or a lapsed qualification flips failing the instant it happens, lighting up against both the SOP and the IATF clause, because both are computed from the same ledger facts as an out-of-cal gage.

The same separations hold. The authority graph is declarative config — a representation-layer artifact: human-diffable, schema-validated, signed, revocable by revert. The exercise of authority is immutable events in the ledger — who did what, when, under which grant. Config and events stay strictly apart. And where authority gates a physical action, the check is evaluated deterministically and locally at the certified boundary alongside the guardian: an out-of-authority command is rejected regardless of what the cognition believes. No agent grants authority, and no agent sits in the path that enforces it.

A gate is only as real as the authority behind the signature.

09  ·  Specifications

The primitives, made concrete.

The substrate has leaned on three nouns on every page — the ontology, the fact ledger's events, and the capability block. A reference others can build to has to specify them, not just invoke them. These three contracts are the load-bearing definitions; everything else in the architecture is computed over them.

The kernel ontology

The invariant entity set the reframe named in passing, now enumerated and closed at the kernel — extended open-world at the edges. Every concept carries a global, stable, opaque identity; extensions may subtype, add attributes, or add relations, but may never redefine a kernel concept, and each extension passes the same validation an artifact does. This is what lets "a customer adds concepts the core doesn't know" coexist with "the core is fixed."

ontology_kernel: # invariant entities — the bedrock entities: - material # substance / part identity - lot # a tracked quantity of material - operation # a step that transforms material - resource # equipment, tool, gage, cell - measurement # an observed value with units + gage - genealogy # the as-built graph linking the above - authority # who may act — §08 - order # the work to be done — §10 identity: urn:dam:{tenant}:{entity}:{stable-key} # global · stable · opaque extension: # open-world, without forking core mechanism: subtype | attribute | relation constraint: must_not_redefine(kernel) validation: schema + golden_check + human_gate versioning: semver_per_concept # additive by default

The event envelope

The fact ledger is append-only, and every fact takes one shape. Fix that shape once and conformance posture, reconciliation, schema migration, and the audit trail all inherit from it. It separates event-time from ingest-time (the §18 time substrate), names the actor and the grant it acted under (§08), threads causation and correlation, version-stamps its own schema so it can be upcast forward and never rewritten (§11), and signs itself so the ledger is tamper-evident.

event: # the one shape all truth takes id: uuidv7 # time-ordered, globally unique type: measurement.recorded # dotted taxonomy tenant: jax-1 # partition key — §12 occurred_at: 2026-06-19T14:03:22.41Z # event-time — when it happened recorded_at: 2026-06-19T14:03:24.10Z # ingest-time — when we learned it actor: { principal: a.reyes, grant: grant/mrb-line-14 } # who — §08 subject: urn:dam:jax-1:lot:LOT-4471-0312 # ontology identity causation_id: <event.id> # the event that caused this correlation_id: <order/op> # the thread it belongs to schema: measurement/v3 # versioned — upcast forward, never rewrite payload: { char: char-07, value: 12.004, unit: mm, gage: GAGE-118 } signature: ed25519:… # tamper-evident, append-only

The block contract

A block is the unit of the engine — a validated, domain-blind capability, of which SPC is one. It declares the ontology types it consumes and produces, the conformance nodes it can discharge, the parameters a tenant configures (and which of those are unsafe to guess and therefore gated), and the envelope that validated it once. Composition is wiring blocks over the ontology by identity — not glue code — which is precisely why bespoke fit never becomes a forever liability.

block_contract: # the unit of the engine — domain-blind id: block/spc-control version: 4.2.0 consumes: [measurement, operation] # ontology types in produces: [control_state, capability] # ontology types out satisfies: [IATF16949/9.1.1.1] # conformance nodes it can discharge parameters: # configured per tenant — never forked subgroup: { gate: true } # unsafe-to-guess → human-gated limits: { method: xbar_r } rule_set: nelson envelope: # what validated it, once tests: golden + property twin_validated: true signed: true compose: over(ontology) # wired by identity, not by glue code
A reference others can build to specifies its nouns — it doesn't just invoke them.

10  ·  The integration substrate

A peer to the systems that already run the plant.

The data fabric named the surrounding systems — historian, MES, ERP, ATE, LIMS — in a single line. In a running plant the integration is the opposite of a single line: it is bidirectional, transactional, and standards-bound, and the platform must arbitrate which system owns which truth rather than assume it owns all of it. "Demote the ERP" is the strongest claim in this document, and it is only true if the platform is a first-class transactional peer — not an expensive read replica.

The landscape, and who owns what

Every system below is a distinct integration with its own semantics and its own system-of-record (SoR). The platform does not seize authority on day one; it declares, per entity, who is canonical and in which direction truth flows. This table is the integration contract in summary form — each row decomposes into a binding artifact.

SystemCanonical owner ofDirectionKey objectsPattern
ERP SAP / Oracleorders, inventory, costs, material & vendor masterbidirectionalproduction orders, confirmations, goods movements, QM resultsOData · BAPI · IDoc
PLM Teamcenter / Windchillpart & revision, BOM, drawings, ECO / ECNinbounditem rev, BOM, GD&T, change ordersREST · ECO→re-val
APS schedulingfinite schedule, sequencebidirectionaldispatch list, capacity, order statusREST · event
CMMS Maximo / SAP PMassets, preventive maintenance, calibrationinbound (+ work-request out)equipment, calibration-due, downtime codesREST · event
WMS logisticswarehouse stock, moves, ASNbidirectionalstock, picks, ASN, kitsREST · event
LIMS labsamples, results, specsbidirectionalsample, result, spec limitREST · file
eQMS TrackWise et al.NCR / CAPA / MRB, auditsbidirectionalnonconformance, disposition, CAPAREST · binds §08
IdP / HR Entra / Workdayidentity, org, competencyinboundusers, groups, qualificationsOIDC · SCIM
BI / Lake Snowflakeenterprise analyticsoutboundfacts, projectionsCDC egress
Incumbent MES transitionallegacy floor transactions, during cutoverbidirectionalcoexist in shadow, then migrate authorityadapter · ISA-95

System-of-record arbitration

Master-data drift is where integrations rot. The platform's open-world ontology must co-exist with the ERP and PLM as authorities for years, not absorb them. So every entity carries a binding that names the SoR, the sync direction and cadence, the key crosswalk, the conflict rule, and the staleness budget at which conformance posture starts to warn. The SoR's authority is absolute on the entities it owns — the platform never silently overwrites SAP's material master.

system_binding: id: binding/material-master entity: material_master system_of_record: SAP-S4/MM # canonical owner — absolute direction: inbound # platform reads, never writes sync: cdc + nightly_reconcile # event where available, batch backstop key_map: # ERP key ↔ ontology id sap.MATNR: ontology.material.id on_conflict: source_wins # SoR authority is absolute staleness_slo: 15m # lag beyond this warns posture

Transactional writeback — the part that's actually hard

A running plant means the platform must post to the ERP and survive every failure mode: a confirmation that times out, a downstream rejection, a duplicate delivery, a partial batch. The writeback is therefore a governed contract in the same family as the actuation and authority contracts — idempotent (exactly-once effect, not merely once delivery), retried with bounded backoff, dead-lettered rather than dropped, compensated by an explicit reverse step when a downstream rejects, and reconciled against the ERP of record on a schedule to catch silent drift. Crucially it binds to an authority grant from §08 — posting a confirmation is an exercise of authority, logged to the ledger as an immutable event.

erp_transaction_contract: id: txn/production-confirmation target: { system: SAP-S4/PP, object: ProcessOrderConfirmation, op: CO11N } trigger: ledger.event(op_complete, scope: op-30-turning) idempotency_key: ledger.event.id # exactly-once effect payload_map: # ontology → ERP / ISA-95 fields order: AUFNR yield_qty: GMNGA scrap_qty: XMNGA confirm_ts: BUDAT isa95: ProductionPerformance # standards binding at the boundary delivery: at_least_once # transport guarantee on_failure: retry: { max: 6, backoff: exponential, ceiling: 30m } then: dead_letter # never silently drop compensation: reverse_confirmation # saga step on downstream reject reconcile: nightly # detect drift vs ERP of record authority: grant/post-confirmation-line-14 # who may post — binds §08 exercise: logged_to_ledger

The order lifecycle

A plant runs on orders dispatched from L4 / APS, and the platform owns their floor-side state machine — receive, acknowledge, schedule, dispatch, run, confirm (often partially, many times), complete, close — with hold/resume and a rework branch that re-enters the line. Every transition is a ledger event bound to the responsible authority and the governing conformance nodes, so the order's history and its compliance posture are the same truth.

order_lifecycle: states: received → acknowledged → scheduled → dispatched → in_process in_process → (partial_confirm)* → completed → closed branches: any → on_hold → (resume | cancelled) completed → rework → in_process # rework re-enters the line on_transition: ledger.event + bind(authority, conformance) source: SAP-S4/PP | APS # dispatched from L4

Standards at the boundary — open-world within

To make "run it over what you have" a product rather than a per-customer integration project, the boundary speaks a defensible standard even though the core stays open-world. The platform maps to ISA-95 / IEC 62264 objects — Production Schedule, Production Performance, and the Material, Equipment, Personnel, and Process-Segment definitions — and exchanges them as B2MML where the customer's middleware expects it. The ontology induces freely inside; the wire is standard. That single decision is what lets a new tenant connect to an existing ESB without a bespoke adapter per object.

Connectivity & transport

Real enterprises sit behind firewalls and route through middleware. The adapter posture is explicit: SAP via OData / BAPI / IDoc, the OT side via OPC-UA, generic systems via REST and durable message bus; reach into on-prem through a cloud-connector or edge agent; authenticate with OAuth2 client-credentials plus mTLS; ingest by CDC where a system emits change events and fall back to bounded polling where it does not; preserve per-key ordering so an entity's events never arrive out of sequence; and keep the privacy invariant that no personal or sensitive data is ever placed in a URL.

integration_adapter: id: adapter/sap-s4-prod transport: [odata_v4, bapi_rfc, idoc] # per object connectivity: on_prem_bridge # cloud connector / edge agent auth: oauth2_client_credentials + mtls ingest: cdc else poll(5m) egress: durable_queue → at_least_once ordering: per_key # preserve order within an entity ot_transport: opc_ua # historian / L2 side outbound_pii: never_in_url # privacy invariant

Identity federation

The authority graph of §08 is meaningless if it is a parallel directory. It federates: single sign-on via OIDC or SAML against the enterprise IdP, user and group provisioning pushed in via SCIM, enterprise groups mapped to platform roles, and a competency feed from the LMS standing behind the live authority posture — the source that makes "a lapsed qualification flips to failing" real. De-provisioning a person in HR revokes their grants and recomputes posture automatically.

federation: sso: oidc # or saml — enterprise IdP provisioning: scim # users & groups pushed from HR / AD role_map: # enterprise group → platform role (§08) "MFG-QUALITY-DIR": mrb-disposition-authority competency_feed: lms # qualifications behind posture on_deprovision: revoke_grants + recompute_posture
An ERP you can only read from is one you haven't actually integrated.

11  ·  The operational substrate

The plant doesn't stop for a deploy.

The moment the platform becomes system-of-record for genealogy, it inherits the plant's uptime requirement — and a reference architecture that is silent on availability, upgrade, scale, and support is silent on the question that actually decides adoption: does it stay up? Continuous re-adaptation governs the configuration. These are the envelopes that govern the platform itself.

Availability & disaster recovery

Recovery objectives are stated per data class, because the classes differ in kind. The fact ledger is the irreplaceable truth — near-zero RPO, replicated active-active, point-in-time restorable. Configuration lives in version control and recovers by redeploy. Projections are derived, so they are never backed up — they are rebuilt by replaying the ledger, which is why "compliance posture is a projection" pays off operationally as well as conceptually. The edge buffer from §18 is the partition-survival mechanism: it holds and drains in order when the link returns.

continuity_target: ledger: { rpo: 0, rto: 5m, mode: active-active, backup: pitr } config: { rpo: 0, rto: 5m, store: git, recovery: redeploy } projections: { rpo: n/a, rto: 15m, recovery: rebuild_by_replay } # derived edge_buffer: { survives: link_loss, drain: on_reconnect, ordered: true }

Upgrade & schema migration without a window

Manufacturing is twenty-four-seven; there is no maintenance window mid-batch. Because the ledger is append-only, its schema evolves by versioned event schemas with upcasting — old events are read forward, never rewritten. Because projections are derived, a projection schema change is a redeploy-and-rebuild, not a destructive migration of live data. The cognition tier deploys blue-green or canary, and platform rollback (revert the deployment) is kept strictly distinct from configuration rollback (revert a commit) — the two are different undo buttons for different layers.

Scale & cost envelope

This is the scale envelope named in §04, given teeth: the dial that turns per tenant while substrate, blocks, and engine stay identical. It states ingest throughput from a full historian, the latency budget for a live-posture query, ledger partitioning, retention and tiering, and a metered, predictable cost basis — so a startup and an enterprise run the same platform at honestly different settings.

scale_envelope: # the dial §04 turns per tenant profile: enterprise ingest: { events_per_sec: 250k, historian_tags: 1.2M } posture_query: { p99_latency: 2s } ledger: { partition: by(site, month), retention: 7y, tier: hot→cold } cost: { metered: per_tenant, basis: agentic_compute + storage }

Self-observability & the support model

The platform observes itself the same way it observes the floor: its health is a projection over its own events, with golden signals — ingest lag, ERP-posting success rate, posture-compute freshness, projection drift — each carrying an SLO and a live state. A breach pages on-call and opens an incident. This is the answer to the only question that matters at 3 a.m. — who do I call when it stops posting to SAP, and how do I know before the plant does? — and it is the same metabolism, turned inward.

operational_posture: # the platform, watching itself signals: ingest_lag: { slo: <60s, state: ok } erp_post_success: { slo: >99.9%, state: ok } posture_freshness: { slo: <5s, state: ok } projection_drift: { slo: 0, state: ok } on_breach: page(oncall) + open_incident rendered_by: same_engine_as_floor_posture # self-similar to conformance
The platform that watches the floor must watch itself the same way.

12  ·  Security & trust

Governance is not security.

Authority (§08) decides who may act; security decides what an adversary cannot do regardless. This platform has an attack surface most manufacturing software does not — it generates configuration from ingested floor data — so its threat model is not a generic SaaS checklist. The trust boundaries, the agentic-generation threat, the OT line, and tenant isolation have to be explicit.

Trust boundaries & data classification

Four boundaries matter, and the architecture already implies three of them. Untrusted ingested documents meet the generator. The determinism line of §07 is also a security boundary. Tenant meets tenant. Operator and vendor meet the platform. Data is classified and handled accordingly — facts, configuration, secrets, personal data, and regulated records each get a distinct regime: encryption in transit and at rest throughout, secrets held in a manager and never written into config or the ledger, and keys rotated under policy.

The agentic-generation threat — the one unique to this design

The onboarding agent induces configuration from SOPs, control plans, recipes, and supplier documents. That is an untrusted-input-to-artifact-generation path: a careless or poisoned document is an injection vector. The decisive point is that the governance machinery is the security control. The generator is sandboxed and holds no ambient authority — it emits proposals, never effects. Every proposal must clear the validation envelope, the golden checks, and the conformance check, then a human gate, before it can do anything. Each artifact carries provenance — which inputs induced it — and nothing generated acts before review. The stance that makes generation trustworthy is the same stance that makes it safe from poisoning.

threat_model: # the surface unique to this design surface: agentic_generation untrusted_input: [sop, control_plan, recipe, supplier_doc] threat: injection | poisoning → malicious_artifact containment: # the governance machinery IS the control - generator: sandboxed, no_ambient_authority # proposes, never acts - output: proposal_only → envelope(tests + golden + conformance) → human_gate - provenance: artifact ← inputs_that_induced_it - effect_gate: signed + authority(§08) + ledger.event invariant: no_generated_artifact_acts_before_review

The OT security line

The determinism boundary of §07 doubles as the security boundary, and it maps cleanly to IEC 62443 zones and conduits: the cognition tier and the certified layer are separate zones, and the actuation contract is the only conduit between them — already a signed whitelist with hard clamps. The guardian that rejects an out-of-envelope command lives at the certified layer, so defense-in-depth holds even if the cognition tier is compromised: there is no inbound path that bypasses the conduit, and no command executes outside the pre-ratified envelope.

Multi-tenancy & isolation

"One platform, every scale" rests entirely on an isolation model, so it is stated outright. Code is shared; data is not. The kernel ontology, the capability blocks, and the adaptation engine are shared as code across all tenants; the fact ledger, configuration, projections, data-fabric adapters, and secrets are isolated per tenant — which the ontology identity scheme already anticipates by carrying the tenant in every URN and every event. Cross-tenant access is denied by default, a tenant's generation is scoped to its own data, residency is per-tenant for sovereignty, and the per-tenant scale envelope of §11 is also the noisy-neighbor control.

tenant_isolation: # what 'one platform, every scale' rests on shared: [kernel_ontology, capability_blocks, adaptation_engine] # code, not data isolated: [fact_ledger, config, projections, adapters, secrets] # per tenant partition_key: tenant # in every event + identity URN residency: per_tenant_region # data sovereignty blast_radius: data: deny_cross_tenant generation: scoped_to(tenant) noisy_neighbor: scale_envelope(§11) # per-tenant quota enforcement: deny_by_default

Records & signatures

The signed-config plus immutable-ledger design is 21 CFR Part 11-shaped by construction: every event is attributable to an actor and a grant, contemporaneous by its dual timestamps, original and tamper-evident by signature, and audit-trailed by the ledger itself — the ALCOA properties fall out of the event envelope rather than being bolted on. What remains for a regulated deployment is procedural, not architectural; the same is true of GAMP 5 validation and ISO 27001 controls, which the block-and-envelope model and the governance trail are built to satisfy.

The governance that makes generation trustworthy is what makes it safe from poisoning.

13  ·  Deployment

The runtime, drawn.

Every view so far is logical. This is the physical one — where each layer actually runs, and how the boundaries of §07, §10, and §12 land on real machines and networks.

Cloud region · per tenantadaptation engine · agentic onboarding · fact ledger (active-active) · projections · governance
Secure conduitsmTLS & OAuth2 · CDC / event ingest · signed config over GitOps · never PII in a transit URL
Enterprise edgeon-prem bridge → SAP · PLM · CMMS · WMS  |  IdP — SSO · SCIM  |  BI / lake egress
Plant site · ×Nedge agent — store-and-forward, local projections, survives link loss · OPC-UA down to the floor
determinism boundary · IEC 62443 zone
OT zonehistorian · SCADA · PLC / motion / robot / SAFETY · the guardian rejects out-of-envelope commands

The cognition tier runs in a per-tenant cloud region (§12 isolation), the ledger replicated active-active for the recovery objectives of §11. It reaches the enterprise only through governed conduits — encrypted, authenticated, change-data-captured inbound and signed-config outbound. Each plant runs a thin edge agent that buffers and drains in order across a link loss (§18), holds local projections so the floor keeps working offline, and speaks OPC-UA to the historian and controllers. Below the determinism line sits the certified OT zone, a distinct IEC 62443 security zone whose only conduit upward is the signed actuation contract — and whose guardian rejects any out-of-envelope command regardless of what the cloud believes. Nothing in the cloud tier is in the interlock path; nothing on the floor depends on the cloud being reachable.

14  ·  Non-functionals

Every quality attribute, traced.

The architecture's non-functional goals, each tied to the decision that satisfies it and the section where it lives — so the "-ilities" are demonstrable, not gestured at.

AttributeHow the architecture satisfies it§
AvailabilityActive-active fact ledger, recovery objectives stated per data class, edge store-and-forward through link loss.§11
ScalabilityOne platform, every scale; only the per-tenant scale envelope turns while substrate and engine stay identical.§04
SecurityGovernance machinery as the control against poisoned generation; sandboxed generator; IEC 62443 OT zoning.§12
MaintainabilityThe bespoke surface is signed, diffable text; adaptation composes validated blocks rather than generating throwaway code.§06
AuditabilityAppend-only, event-sourced ledger; compliance posture is a live projection, never a binder assembled before an audit.§05
PortabilityOpen standards in the fabric and exportable, human-readable, version-controlled compositions mitigate lock-in.§17
AdaptabilityAgentic re-adaptation: the reality is the spec, continuously — no replatforming cliff.§02
IsolationShared code, per-tenant data, cross-tenant denied by default; tenant carried in every URN and event.§12
ComplianceBorn-aligned conformance; the event envelope is 21 CFR Part 11-shaped by construction (ALCOA falls out of it).§05
ObservabilityThe platform watches itself the same way it watches the floor — operational posture is a self-projection.§11
SafetyDeterministic, certified control below the boundary; no agent in the interlock path, ever.§07
IntegrabilitySystem-of-record arbitrated per entity; idempotent, compensated writeback; ISA-95 spoken at the boundary.§10

15  ·  Validation

Validating a system that keeps changing.

Computer-system validation assumes a frozen system; continuous adaptation breaks that assumption. The resolution, named as a frontier in §17 and stated as strategy here, is to validate the generator and the envelope — not every output it will ever produce — and to scope re-validation to the delta.

A block is validated once, by its envelope — golden checks, property tests, and twin validation, then signed; its instances inherit that validation. You qualify the generator together with the validation envelope it must pass, so any artifact that clears the envelope is trusted by construction rather than re-validated by hand. When a governing spec changes, the conformance layer emits a precise re-validation worklist — exactly the affected parts and nothing more — which is the mechanism that makes a continuously adapting system validatable at all. Any change that drives a physical action is simulated against a digital twin before deploy. For the regulated case, this maps cleanly onto risk-based GAMP 5: the block-and-envelope model supplies the documented qualification, and the conformance posture plus the immutable ledger supply continuous IQ/OQ/PQ evidence rather than a point-in-time snapshot. The remaining work is regulatory engagement, which §17 names honestly.

validation_strategy: unit: block.envelope = golden + property + twin, signed # validated once; instances inherit generator: qualify(generator + envelope) # trust outputs by construction output: any artifact passing the envelope is trusted change: spec_change → scoped_revalidation_worklist # delta, not the whole system — §05 physical: twin_validated before any actuation deploy # §07 regulated: gamp5_risk_based # evidence = posture + ledger = continuous IQ/OQ/PQ
You validate the generator and the envelope — not every output it will ever produce.

16  ·  Conformance

What counts as conformant.

This is a reference architecture, not a product. An implementation conforms to it if — and only if — these invariants hold. The document preaches conformance bindings for the factory's specs; here it binds itself.

The line is drawn at the invariant

Strong opinions on what is universal — material, lot, operation, genealogy, measurement, authority, order — and zero opinion on the variable. The substrate is fixed; the surface is bespoke.

Determinism below, cognition above

Safety-bearing control stays deterministic and certified, with no agent in the interlock path. Any platform-initiated physical action passes a signed, clamped actuation contract enforced by a local guardian.

One immutable truth

A single append-only, event-sourced fact ledger. Every interpretation — audit view, engineer view, posture, cockpit, platform health — is a projection over it, never a separate store.

Bespoke by composition

Adaptation composes and configures validated, domain-blind blocks. True code generation is the gated exception, validated through the envelope so bespoke fit never becomes a forever liability.

The surface is signed text

The entire bespoke surface is legible, diffable, signable, version-controlled text. The human gate is a review, the validation envelope is CI, the audit trail is history.

Open-world ontology

A tenant can add concepts the core does not know without forking the core; extensions are validated and may never redefine a kernel concept.

Authority is a primitive

Who-may-act is governed, scoped, expiring, and enforced deterministically where it gates physical action. Granting authority is itself a gated, signed, audited act.

System-of-record is arbitrated

The platform co-exists with ERP and PLM, declaring the canonical owner per entity; any writeback is idempotent, compensated, and reconciled.

An implementation conforms by what it refuses to vary — not by what it builds on top.

17  ·  The hard problems

What this costs, stated honestly.

Validation of adaptive systems under GxP / AS9100

Computer-system validation assumes a frozen system; continuous adaptation strains it. Block-and-envelope validation plus the conformance layer is the path — but it's a frontier, and it needs regulators on board.

The OT / safety boundary in practice

Clean in a diagram; messy against real PLC fleets and legacy interlocks. The safety-architecture proof is non-trivial.

Data & document quality

Adaptation quality is bounded by the legibility of the floor's data, control plans, recipes, and SOPs.

Human factors & transferability

If every plant's software is bespoke, a mobile workforce loses transferable skill — which argues for a consistent interaction grammar even as specifics are bespoke.

Inverted lock-in

A wholly agent-generated system is a new dependency — mitigated by open standards in the fabric and exportable, human-readable, version-controlled compositions.

The unsafe-to-guess core

Subgrouping, spec provenance, risk tier, CCP designation, disposition authority — gated decisions, across every capability.

18  ·  Making it land

Sound underneath. Coherent on top.

An architecture earns adoption only when it passes two tests at once — is the mechanism elegant and correct beneath the surface, and is the result a coherent, delightful experience for the person who must live in it? These proposals pass both, and none of them moves the line: every one lives above the control boundary and reinforces the gate rather than eroding it.

01

Shadow mode is the default first run

For its first 60–90 days at any customer, the platform runs observe-only: it ingests real data, induces the ontology, and renders a live conformance and value posture with zero actuation authority — predicting and matching reality beside the incumbent MES before it is granted a single command.

Sound underneath

No new subsystem. Shadow mode is simply the platform with the actuation contract set to null authority — the control boundary already exists, so observe-only is free.

Coherent on top

The demo is the product. Trust is earned on the floor — watch it match reality for a quarter — not asserted in a slide. It is also the reversible on-ramp the buyer needs.

02

One truth, rendered for everyone

Extend one truth rendered twice into the universal pattern: the auditor's binder, the engineer's process view, the plant manager's production cockpit, and the executive's value posture are all projections over the same immutable ledger — each in its own vocabulary.

Sound underneath

Projections all the way down. No new stores, no reconciliation between views — the strongest possible evidence the abstraction line is drawn in the right place.

Coherent on top

Everyone opens the app and sees their world in their language, and it is all the same truth underneath. The unification is the magic.

03

Calibrated confidence, a risk-ranked gate

The onboarding agent must express what it is unsure of — "60% this is a CCP, confirm" — and human gates must be routed by risk, with trusted auto-merge for low-risk deltas, so attention goes where it matters.

Sound underneath

Confidence calibration plus a priority queue makes the review load mathematically tractable, and turns the unsafe-to-guess core from a list into a mechanism.

Coherent on top

The reviewer's inbox is curated — "the three decisions only you can make today," not four hundred pull requests. Taste applied to attention keeps the gate real at scale.

04

Time and edge as first-class substrate

Explicit event-time vs. ingest-time semantics, store-and-forward at the edge, and deterministic reconciliation on reconnect — promoted into Stratum A, because a fact ledger fed by historians and ATE inherits manufacturing's worst data problem: timestamps lie and links drop.

Sound underneath

The hard, correct plumbing nobody sees and everybody depends on. Rolling Cpk and the simultaneous posture flip are only true if ordering is defensible.

Coherent on top

The visible result: the system never lies, never drops a measurement, and works when the network does not. The user never has to think about it.

05

A design system for the bespoke surface

Generate every operator screen and dashboard from a constrained component grammar and shared interaction tokens derived from the ontology — bespoke content, consistent grammar. The direct answer to the transferability problem.

Sound underneath

A typed, validated component library — the surface analog of the capability blocks. The same generator discipline, applied to UI.

Coherent on top

The Human Interface Guidelines insight exactly: a worker who moves between plants is instantly fluent. Bespoke where reality differs; familiar where it should not.

06

Undo that understands the physical world

Generalize the conformance layer's scoped re-validation delta into physical-state reconciliation: when intent rolls back, compute the material blast radius from genealogy and emit a corrective and quarantine worklist. git revert restores intent; this reconciles the parts you already made.

Sound underneath

Elegant reuse — genealogy and the ledger already hold everything needed to compute the affected WIP. The mechanism is already there.

Coherent on top

Undo that knows the difference between a config and a part already on the floor. Reversibility that is honest about physics.

Standardize the physics. Bespoke the experience. Make both true at once.

19  ·  The fractal

SPC is the whole platform in miniature.

Statistical process control is one entry in the capability library — and it has its own invariant kernel, its own adaptation layer, its own tenant profile. The same pattern holds at the level of a single quality method and at the level of the entire platform: a fixed validated core, agentic adaptation, a governed bespoke surface.

That self-similarity is the strongest evidence the abstraction line is drawn in the right place rather than a convenient one. Build the platform and SPC is one of its first, best-defined capabilities. Build SPC well and you've prototyped the platform's whole metabolism in one domain.

The thesis in one line

Standardize the physics. Bespoke the experience. Gate the decisions that are unsafe to guess.

A rock-solid invariant substrate, a shared engine that adapts by composing validated blocks rather than generating throwaway code, and a bespoke surface generated to each customer's reality — with a hard line keeping deterministic control below and probabilistic cognition above.

Discuss the state of the project

Appendix  ·  The vocabulary

Every coined term, defined.

This architecture introduces a precise vocabulary on purpose. Each term resolves to one idea and one home in the document.

TermDefinition§
Adaptation engineStratum B — the shared engine that composes and configures validated blocks into per-tenant output, without forking the core.§03
Authority grantA governed, scoped, expiring assignment of who may do what — the authority primitive, bound to conformance and logged on every use.§08
Bespoke surfaceStratum C — the generated experience and customer logic, unique to each tenant.§03
BlockThe domain-blind, validated unit of the engine; declares the ontology types it consumes and produces and the conformance nodes it discharges. SPC is one.§09
Born alignedConformance designed in and proven continuously from ledger evidence, rather than assembled into a binder before an audit.§05
CompositionBuilding bespoke fit by wiring validated blocks over the ontology by identity, rather than generating throwaway code.§09
Conformance bindingA bidirectional, evidence-backed link declaring which requirement nodes a system part satisfies.§05
Conformance postureThe live satisfied / at-risk / failing state of compliance, computed as a projection over the ledger.§05
Data fabricThe layer that maps external sources and sinks — historian, MES, ERP, LIMS — into the ontology.§10
Determinism boundaryThe hard line keeping deterministic, safety-bearing control below and probabilistic cognition above.§07
EventThe single append-only envelope every fact takes: id, event- and ingest-time, actor, causation, schema, signature.§09
Fact ledgerThe canonical, append-only, event-sourced store of truth from which all projections are computed.§03
Generation envelopeThe gated validation boundary — tests, golden checks, conformance, signing — that makes a generated artifact trustworthy.§02
Golden checkA known-good reference result that generated output must reproduce to be accepted.§09
GuardianThe deterministic, local enforcer at the certified layer that physically rejects any out-of-envelope command.§07
Invariant substrateStratum A — the shared, trusted, fixed foundation: ontology, fact ledger, data fabric, governance.§03
Ontology (open-world)The invariant entity kernel that a tenant can extend with new concepts without forking the core.§09
Operational envelopeThe pre-ratified operational design domain within which a cell may run autonomously, failing safe outside it.§07
ProjectionAny derived, recomputable view over the ledger — the audit view, the engineer's view, a posture, a cockpit.§05
Representation layerThe principle that the entire bespoke surface is legible, diffable, signable text — GitOps for the factory.§06
Requirement nodeAn atomic, stably-identified decomposition of a governing spec — an IATF clause, a GD&T callout, a critical control point.§05
Scale envelopeThe per-tenant dial — throughput, latency, retention, cost — that varies while substrate and engine stay identical.§11
Shadow modeAn observe-only first run with zero actuation authority, predicting and matching reality before it is granted a command.§18
Spec-as-dataTreating a governing specification as a structured, addressable target rather than prose.§05
System of recordThe canonical owner of a given entity, arbitrated per entity so the platform co-exists with ERP and PLM rather than replacing them.§10
Tenant isolationShared code, per-tenant data: blocks and engine shared, ledger and config isolated, cross-tenant denied by default.§12
The fractalThe self-similarity by which one capability (SPC) mirrors the whole platform: fixed core, agentic adaptation, governed bespoke surface.§19

Appendix  ·  Revision history

Previous versions.

Each revision is preserved as a snapshot. This page always reflects the latest; earlier states are linked below.

VersionWhat changed
v0.9.5 — currentThe reference-completeness pass toward 1.0: a deployment topology, the quality-attribute model, the verification & validation strategy, and conformance criteria for implementations of the architecture.
v0.9Specifications (ontology kernel, event envelope, block contract), Security & trust (the agentic-generation threat model, the IEC 62443 OT line, multi-tenancy isolation, Part 11 records), the Glossary, and the floating dock.
v0.8The Integration substrate (system-of-record arbitration, transactional ERP writeback, the order lifecycle, ISA-95 at the boundary, identity federation) and the Operational substrate (availability & DR, zero-window upgrade, the scale envelope, self-observability).
v0.7The Authority substrate — authority as an invariant primitive, with scoped expiring grants, conformance binding, and deterministic enforcement at the certified layer.
v0.6"Making it land" — six adoption proposals: shadow mode, unified projections, calibrated-confidence gating, the time/edge substrate, a design system for the surface, and physical-state reconciliation.
v0.5Initial reference architecture: the inversion, the seven tenets, the three strata, every-scale, conformance, representation, control, the hard problems, and the fractal.