Forge Platform

Industrial data operations for a manufacturing enterprise

Onboarding tutorial · two tracks from one landing fork · software-dev / contributor onboarding and an end-user overview of the framework.

Last verified: 2026-11-13 against the repository reh3376/forge at the merge of Pull Request (PR) 95 (branch main): every slide reviewed against the tree and the key documents (FB-114), the three-layer process control framework (D-11) added to both tracks.

Companions: README.md · docs/VISION.md · docs/WHERE-WE-ARE-GOING.md · docs/WHERE-WE-ARE.md · docs/ROADMAP.md · docs/PRINCIPLES.md · BACKLOG.md

Choose Your Path

Two walkthroughs branch from here.

Table of Contents

Software Dev Path: F1 Opening → F2 The Hub ↔ Spoke Contract → F3 Storage → F4 Spec-First Governance → F5 The Plant-Floor Module → F6 Modules, Module Builder, forge-display → F7 Context, Curation, Decisions → F8 Security, Identity, Federation → F9 Contributing → F10 Conclusion

End User Path: U1 Start Here → U2 How Data Flows → U3 The Hub You Run → U4 Your Systems as Spokes → U5 The Plant Floor → U6 Context, Products, Decisions → U7 Governance for Users → U8 Screens → U9 Identity, Roles, Credentials → U10 Operations → U11 Where to Go Next

Use the left-margin sidebar for section and diagram navigation.

F1 · Opening

Nav: ⇤ Table of Contents (TOC) · ⇅ Landing fork · F2 →

What Forge is, the thesis behind it, the twelve problems it is built to solve, what the finished system looks like, where it honestly stands today, and how to read its documents.

What Forge Is

Forge is the industrial data operations platform for a manufacturing enterprise.

• It connects every operational system a plant runs on: Supervisory Control and Data Acquisition (SCADA)/PLC, Manufacturing Execution System (MES), Warehouse Management System (WMS), Computerized Maintenance Management System (CMMS), Enterprise Resource Planning (ERP), Quality Management System (QMS), historians, network management, lab and scanner devices.
• It turns their output into one governed record type with manufacturing context attached.
• It curates that into decision-quality data products with lineage and quality objectives.
• It renders every operator and management interface from declarative specifications.
• Its own management modules (forge-mes, forge-whs, forge-cmms, forge-ot, …) are optional: a site can run Forge purely as the integration and governance layer over the software it already has, or replace that software module by module.

Forge is also a governed engineering platform: contracts between components are machine-checked specifications with hash integrity and owner approval, so that neither people nor Artificial Intelligence (AI) coding agents can change an interface silently.

The Thesis

Bad manufacturing decisions come from missing quality, context and correlation, not from missing data.

Poor decisions are far more costly than generally realised: the cost is spread across many units and shifts, and the root cause of a confidently wrong decision is rarely captured.

The Twelve Problems

Each is stated as it is experienced in a plant; each has a component that carries it and a definition of solved (docs/VISION.md §2).

The Finished System

Where We Are Today · Honest

From docs/WHERE-WE-ARE.md §1, the snapshot at PR 95:

1. The hub ↔ spoke contract works end to end: a spoke registers, is checked against its FACTS spec, pushes records that are persisted, is pulled (Collect, Backfill, Subscribe) and receives write-backs, over TLS/mTLS both ways with per-spoke tokens.
2. The OT module runs inside the hub with OPC-UA connections, a tag engine, ISA-18.2 alarms, the full control-write defense chain, and drives the MES changeover sequence including the PLC Common Industrial Protocol (CIP) runner. Since the one-clock steps of 2026-11-13 no record builder invents a source time, the OPC-UA server's clock is read and every stamp corrected by its measured offset, and every spoke declares how it is time-governed in its FACTS contract (FB-088, FB-094, FB-090).
3. forge-mes is Go and not yet built: the imported NestJS backend and Next.js frontend stand in as the interim bridge and speak the spoke contract; the Go rewrite (FB-076) is decided and designed (docs/decisions/forge-mes-go.md, signed 2026-11-03); the Go SDK scaffold is its first step.
4. Governance is real for four frameworks (FATS, FACTS, Forge Transport Test Specification (FTTS), Forge View Test Specification (FVTS)) plus FHTS hashing; the other seven are stubs or planned. forge-display does not exist yet; its contract (FVTS) does, with a runner and golden messages.
5. Not yet: scoped roles in the gateway, mod_mes in the hub, the Go module SDK, the hub-of-hubs federation, Kubernetes, and any management module in Go.
6. The three-layer process control framework (PC-L1 Proportional-Integral-Derivative (PID) in the PLC, PC-L2 Model Predictive Control (MPC), PC-L3 Subject-Matter Expert (SME) agents) is decided and signed by the owner (D-11, 2026-11-13); nothing of it is built, and nothing is built before its FSDs (F5).

The Key Documents and How to Read Them

• VISION.md changes only when a decision in ROADMAP.md §1 changes.
• WHERE-WE-ARE-GOING.md changes when a milestone or the sequence changes.
• WHERE-WE-ARE.md changes before any push that changes the state it describes (rule since 2026-10-16).
• ROADMAP.md holds decisions in force (A-1 … A-10, R-1 … R-19), the workstreams, the proposed sequence and the owner's decision queue (D-1 …).
• BACKLOG.md is the unit of work: one item per PR; a finding is fixed or recorded, never skipped.
• PRINCIPLES.md holds the design principles, technical invariants, the governance pattern, the decision frame, adapter tiers, technology choices and lessons that still bind.

Design records for decisions the owner must sign live in docs/decisions/ (roles.md, forge-mes-go.md, one-clock-ot-source-time.md, one-schema-registry.md, process-control-framework.md, all signed); an agent-facing context document accompanies the last in docs/personal/.

Repository Tour

F1 Recap → F2

• Forge: one governed record type, context attached, curated into data products, interfaces rendered from specs, contracts hashed and owner-approved.
• Twelve problems, each carried by a named component with a definition of solved.
• Today: the contract works end to end, the OT module runs in the hub, governance is real for four frameworks; forge-mes in Go, forge-display, scoped roles, federation and Kubernetes are not built.
• Read VISION once, GOING once, WHERE-WE-ARE every time.

Next: what actually crosses the hub boundary.

F2 · The Hub ↔ Spoke Contract

Nav: ← F1 · ⇤ TOC · ⇅ Landing fork · F3 →

One contract, forge.v1.AdapterService, carries everything between a spoke and its hub. This section covers the twelve RPCs, the one record type, the transport, and what happens at Register and at Ingest.

AdapterService · Twelve RPCs

• Compiled protobuf over gRPC; JavaScript Object Notation (JSON) over gRPC is forbidden (decision A-1).
• Go and Python bindings generated from one proto set (src/forge/proto, src/forge/proto_gen, go/gen/forge).
• Spokes are Python inside the hub or external processes in any language that speaks the proto.
  Speaker notes

  • The rule "spokes never talk directly to each other" holds: every exchange goes through the hub. Spokes may publish to the Forge broker for real-time data, but the contract is the hub's.

ContextualRecord · The One Record Type

• RecordContext carries the context field registry slot for slot, on the proto and in Go, with every producer and the TimescaleDB table following (FB-013).
• A naive datetime or an offset-less string is rejected at the model (forge.core.clock, FB-014); ruff's DTZ rules block CI.
• The hub stamps ingestion_time with its own clock on receipt; the spoke's stamp is kept as sent_time; nothing is invented (FB-087).
• No record builder invents a source time either: a value without a source stamp is refused unless its connection declares source_timestamp_origin: forge; then Forge's read time stands in and the record says so (source_clock, source_uncertainty_seconds), and the refusal is on health, status, API and CLI (FB-088, 2026-11-13).
• Every schema reference uses one grammar, forge://schemas/<spoke>[/<Entity>][/v<version>], held at every boundary (FB-008).
  Speaker notes

  • The context field registry (src/forge/core/registry) and the manufacturing entity catalog (docs/core/manufacturing-entity-catalog.md) define what each slot means, so "area" is the same thing in every spoke.
  • sent_time becomes spoke_time under the one-clock design (D-9, signed 2026-11-03) when the hub-to-spoke time exchange lands (FB-092).

Transport · gRPC, TLS/mTLS, Tokens

Code: src/forge/transport/grpc_server.py (hub), spoke_client.py (spoke side), grpc_channel.py (retry), proto_bridge.py (proto ↔ model), transport_adapter.py (adapter base).

Ingest · What Happens at Register and at Ingest

• forge.ingest.facts_check verifies the spec's hash before trusting it; a spoke whose manifest or hash does not match is refused.
• One hub-clock reading per batch (IngestPipeline.ingest → stamp_receipt).
• Every link's clock offset is measured and exposed on AdapterHealth.clock, GET /v1/ingest/stats, the OT connection status and OpenTelemetry (forge.clock.offset, forge.clock.out_of_tolerance); the provisional tolerance is 1 s (FB-089). Enforcement is FB-093 (D-9 signed 2026-11-03: per-link tolerance classes, never silent).
• Curated records are persisted with the raw ones (FB-009).
  Speaker notes

  • HubIngestServicer replaced the original in-memory servicer (FB-053); before that, records were queued and never routed.
  • Push persisted and FACTS-checked at Register since FB-053; pull since FB-061 and FB-071.

Pull, Backfill and Write-back

• Collect: the hub asks a spoke for records on demand (bounded by the spoke's declared capabilities).
• Backfill: historical ranges, used by historian spokes and the forge-mes AuditLog backfill (FB-071).
• Subscribe / Unsubscribe: live change streams.
• Write: the hub writes back into a source system through a session-bound callback; the source's own rules still apply, and in the OT module the write first passes the defense chain (F5).

Everything a spoke can do is declared in its FACTS spec (capabilities, data_sources, error_handling); the runner checks the declaration, and Register checks the manifest against it.

F2 · Honest State

Next: where the records land.

F3 · Storage and the Hub-Owned Databases

Nav: ← F2 · ⇤ TOC · ⇅ Landing fork · F4 →

The hub owns the databases (decision A-6). This section covers the engines, routing, the twelve migrations, Forge-issued credentials, the "observe → shadow → own" path for module data, and the two schema registries.

The Hub Owns the Databases (A-6)

• Modules hold only Forge-issued credentials and never connect on their own.
• Storage is polyglot by invariant: record types route to the engine that fits them; no single database serves every access pattern.
• Serving is API-first: consumers go through versioned APIs defined by FATS specs, never to a database directly.
  Speaker notes

  • The hub's health orchestrator probes all seven compose-stack components (/v1/health, /readyz, FB-006).

Routing

• forge.storage.factory builds the engines from configuration; the router picks the engine per record.
• Today the routing registry is in memory and empty on every start, so routing falls through the default routes by data_type. That is the subject of the one-schema-registry design record (D-10, below).
  Speaker notes

  • forge.storage.engines.timescale writes every RecordContext slot (FB-013); the migration test holds the writer's column list equal to the table's.

Migrations · Twelve, and the Runner

forge migrate up | status | down
python -m forge.storage.migrations.run up --target postgres     # the runner behind the CLI

• Online runs go through asyncpg on SQLAlchemy's async engine (FB-003).
• The whole downgrade runs in one transaction; head → base → head is verified clean on a throwaway TimescaleDB container (FB-098, FB-101).
• tests/storage/test_migrations.py reads the migration source and holds it to the models and the writers.
  Speaker notes

  • A migration is never edited after it has been applied somewhere; a repair is a new revision (012 is the pattern).
  • Postgres and the time-series target share the chain; the hypertable step runs only when the timescaledb extension is present.

Forge-Issued Credentials · forge db access

forge db access grant forge-mes mod_mes --level write
forge db access grant forge-mes forge_canonical --level read
forge db access issue forge-mes --host localhost      # prints DATABASE_URL=... once
forge db access list | revoke ...

• A spoke role (forge_mod_<x>) has no way in until issue runs ALTER ROLE … WITH LOGIN PASSWORD with a password Forge generated; re-issuing rotates it.
• The password is shown once and never stored; the grant, the issue and every refusal are written to forge_core.access_audit (FB-003, FB-057 step 1).
• READ: usage and select, now and by default on future tables. WRITE: also insert, update, delete and sequences. ADMIN: also create on the schema (the interim MES bridge runs its own Data Definition Language (DDL) through Prisma until the hub owns that DDL).
• Protected schemas (forge_core, forge_canonical, curated, lineage) cannot be granted for writing.
  Speaker notes

  • PersistentAccessController is the in-memory controller with every change written to the store the moment it is made; the storage factory and the CLI share it.
  • Open: the bootstrap read grant on forge_core covers only the four tables that existed at 002 (FB-100, decided with FB-057 step 2).

Observe → Shadow → Own

• The hybrid path from docs/DB_ORCHESTRATION_FRAMEWORK.md: adapters read spoke databases, a shadow writer mirrors into the hub, ownership transfers per module.
• Step 1 (grants and issued credentials) is delivered; steps 2–5 (the MES data into mod_mes) follow the forge-mes Go design, signed 2026-11-03 (FB-057, D-3).
• forge.storage.shadow and forge.storage.backfill are the shadow writer and the historical backfill.
  Speaker notes

  • "Own" is the end state for every management module: the module's schema lives in the hub's PostgreSQL and the module never carries a password it created itself.

Two Schema Registries · D-10

The design record docs/decisions/one-schema-registry.md (round 1 2026-10-26, signed 2026-11-03) folds routing into the F20 registry as a placement facet: ten proposals, eight questions answered by the owner one at a time, eight implementation steps, one PR each (FB-097, D-10).

F3 · Honest State

Next: the headline section, governance.

F4 · Spec-First Governance

Nav: ← F3 · ⇤ TOC · ⇅ Landing fork · F5 →

The spec is the contract. This section is the headline for contributors: spec-first governance, the four layers every framework shares, the family of frameworks and their state, hashing and the owner's approval, the anatomy of a FACTS spec, and how to run the gates.

Spec-First, Not Test-First

• The spec defines what must exist and how it must behave; the implementation serves the spec; the runner enforces conformance; the CI gate blocks deviation.
• A FATS spec that says GET /v1/data-products/{id} returns 200 with a given shape is a prior commitment, not a test of an existing endpoint.
• Drift is caught by the runner; a spec change is a visible diff in review.
• A behavioural change is a spec change, and a spec change is reviewed. No specification field is silently ignored.

Rules carried over from Multi-Dimensional Emergent Memory Graph (MDEMG)'s UxTS and confirmed in practice:

• A spec with zero assertions fails; it does not pass (the "0/0 problem").
• Parity: schema fields the runner does not enforce are reported, never ignored; a single unimplemented field is a hard fail.
• Runners produce structured verdicts with check IDs, spec references, violation details and timing, not bare pass/fail.
  Speaker notes

  • Lineage: FxTS is adapted from MDEMG's UxTS framework family. The same governed-memory tooling (MDEMG/Jiminy) watches over the agents working on this repository (F9).

The Four Layers

The Family

Governance is declarative by invariant: quality, lineage, normalization and security rules are specifications, not code paths.

FHTS · Hashing and the Owner Approval

• Every governed spec carries an integrity block: spec_hash, hash_state, previous_hash, approved_by, approved_at, change_history naming who or what changed it.
• The content hash excludes the whole integrity block (a history entry refers to the hash itself); canonical JSON uses sorted keys, compact separators and ASCII escaping, so the digest is portable.
• Hash verification is independent of assertion execution: a spec can pass every assertion and still have hash_verified=false if it was modified. Two orthogonal signals.
• Only the owner approves a spec hash. Agents re-stamp to pending_review and never approve on the owner's behalf. approve is refused when the hash no longer covers the content.
• The hub's Register check verifies a spoke's FACTS hash before accepting the spoke.
  Speaker notes

  • Problem P-7: the more AI assistance a team uses, the larger the risk of a silently relaxed timeout or dropped required field. Hashing makes the change visible in the spec's own history and fails CI until the owner approves it.

A FACTS Spec, Anatomically

• Nine specs today: whk-wms (the reference), forge-mes, bosc-ims, whk-cmms, whk-erpi, whk-nms, next-trend, scanner-gateway, ot-module.
• The runner validates every spec against the JSON schema first (facts:schema-valid) and reads its enums from the schema (FB-080).
• The developer guide, docs/governance/facts-developer-guide.md, walks the schema, how to write a spec, running the runner, common failures and cross-spoke consistency.
  Speaker notes

  • Adapter tiers and what they mean: docs/PRINCIPLES.md §5. The OT tier's vocabulary gap in FACTS v0.1.0 is decision D-8 (decided 2026-11-03: extend the enums, FB-079).

Running the Gates

forge governance specs                       # every spec's hash state, approver, hash still verifies?
forge governance specs --pending             # what awaits the owner
forge governance validate-spec <spec.json>   # against its framework schema
forge governance run facts whk-wms           # one framework, one spec; exit 1 on any failure
forge governance stamp <spec.json>           # after an edit: history entry, pending_review, no approver
forge governance approve <spec.json> --by reh3376   # the owner, on their own word, never on their behalf

• run covers FATS, FACTS, FVTS and FTTS (FB-021, FB-083).
• The hub test suite holds FATS in both directions: every served route has a spec, every spec names a served route.
• The FVTS runner has a render-profile baseline and golden messages; a module can only tighten the baseline, never loosen it.
  Speaker notes

  • When you add a hub route you add a FATS spec; when you add a spoke you add a FACTS spec; when a module exposes a surface it adds an FVTS spec. The gate is where you find out you forgot.

F4 · Honest State

Next: the module that reaches the plant floor.

F5 · The Plant-Floor Module (forge-ot)

Nav: ← F4 · ⇤ TOC · ⇅ Landing fork · F6 →

forge-ot is the most mature module and lives in this repository. This section covers the tag engine, ISA-18.2 alarming, the control-write defense chain, the MES changeover, the scripting SDK, the Ignition bridge, the one-clock principle, and the three-layer process control framework the owner decided on 2026-11-13 (D-11).

What It Is

• A thin, open wrapper over OPC-UA: asyncua owns the wire protocol (pinned ==2.1.0, FB-085); Forge owns tags, alarms, writes, scripting and history.
• Hosted inside the hub with PLC connections, supervision and liveness (forge.modules.ot.host, FB-069, FB-070).
• Replaces the vendor SCADA/HMI layer (Ignition) problem by problem: tag engine, alarming, scripting SDK, i3X-shaped REST, MQTT; where a site keeps its vendor product, the Ignition bridge runs a read-only parallel validation.
• HMI/SCADA itself is an optional module activated per site (decision A-4); forge-display renders the surfaces (A-3).

Tags and Providers

• TagDefinition, TagValue, QualityCode, DataType are the models; every value carries quality.
• Context resolvers attach site, area, equipment, lot, shift and mode to OT records; the batch context resolver wired to MES is open (FB-020).
  Speaker notes

  • The OT module's DataValue and TagValue still coerce a naive datetime to Coordinated Universal Time (UTC) because OPC UA DateTime is UTC by definition; the source-time correction landed with FB-088 and FB-094 on 2026-11-13 (below).

Alarms · ISA-18.2

• Seven-state ISA-18.2 machine, nine alarm types (HI, HIHI, LO, LOLO, digital, rate-of-change, quality, communication, custom).
• Event-sourced journal; REST under /alarms (active, history, config, ack, shelve).
• Integrations: MQTT publish, RabbitMQ fan-out, CMMS auto work orders.
  Speaker notes

  • Alarm presentation (annunciation, priority colours, staleness) is forge-display's job from the FVTS spec, not the module's.

Control Writes · The Defense Chain (A-7)

• Safety stays in the core: roles, interlocks, confirmation, read-back and audit are enforced in forge-core/OT, never only in a UI.
• Server-side two-step review with reason codes and REJECTED_REVIEW since FB-074; multi-party approval follows the role model (D-1, signed 2026-11-03; FB-075).
• The audit record goes to the hub store and to an external publisher (FB-066, FB-067).
• The FVTS contract binds every UI action to a required role, a confirmation mode and the statuses it must handle; the render profile decides whether a surface may write at all.
  Speaker notes

  • "Solved when": no path exists from any interface to a PLC that does not pass the chain, and every write is reconstructible from the audit log (docs/VISION.md P-6).

The MES Changeover

• The orchestrator runs the changeover sequence against the PLC through the CIP runner, with recipe integration turning an MES recipe into batched PLC writes through the defense chain (FB-062, FB-065).
• REST endpoints for confirm-start, retry-recipe, resume and connection restart sit behind the hub's adapters:write scope; the hub user is the actor on the MES write, the audit record and the events (FB-082).

The Scripting SDK · forge.* Replaces system.*

• Python 3.12+ engine replacing Jython 2.7: discovery, loading, hot reload; a PEP 302 import allow-list sandbox; @timer, @on_tag_change, @api.route triggers; area and tag-pattern RBAC; an append-only audit ring buffer.
• The migration map covers all 52 system.* calls; 42 Tier 1 scripts are identified for conversion (docs/p7-ot-module/).
  Speaker notes

  • The SDK lives in src/forge/sdk/scripting; the OT module's user scripts in src/forge/modules/ot/scripts.

One Clock, Governed by the Hub

The owner's principle (2026-10-18): records from different sources only reconcile if their timestamps come from the same master time.

Three Layers of Control · PC-L1 / PC-L2 / PC-L3 (D-11)

• New, not the classic control hierarchy (owner, F-2): portions of layers 1 and 2 have run in industry for years; the whole, with PC-L3 and the autonomy model, has not. The distillery's seven batch processes are an example only; the framework is for every industry Forge serves (F-6).
• One vocabulary for PID and MPC: Process Variable (PV) (the variable controlled), Setpoint (SP) (its target), Manipulated Variable (MV) (what the controller moves), Disturbance Variable (DV) (a disturbance); "CV" is retired because it means two different things (V-1 to V-4). Logix PIDE.CV maps to MV at the PLC boundary.
• PC-L2's two goals: consistent control of a complex loop, and predicting disturbances to act before they manifest (F-3); it improves its own model and tuning (F-4) under the autonomy model on the next slide.
• Strict adjacency (H-1): PC-L3 reaches PC-L1 only through PC-L2; if PC-L2 is offline, PC-L3 writes recommendation logs only (H-8).
  Speaker notes

  • Source: docs/decisions/process-control-framework.md §1, §2.1 and §2.2, with the companion context in docs/personal/. The layers are named PC-L1/2/3 so they cannot be confused with the reference architecture's L1–L5 or with ISA-95 levels (V-5).

What Never Changes, and How Autonomy Is Earned

• Every PC-L2 self-improvement category (model parameters, tuning, model structure, operating limits) and every PC-L3 action type (targets; limits and priorities; controller configuration; schedule requests) is Off, Propose or Autonomous; everything ships Off (AU-1, L2-10, L3-4).
• Autonomy is earned per category: four confidence signals (prediction accuracy, the outcome of promoted changes, the human agreement rate, shadow-run performance), each over its own threshold, for a duration and a minimum number of evaluated events; the framework ships no values, a user enters them; a person grants the switch by default; revocation is automatic (AU-3 to AU-9).
• Changes are versioned and validated by a backtest plus a shadow run; rollback is a default an administrator may adjust, and without it a category is Propose at most (AU-10 to AU-16). Shed: heartbeat bad, and the PID resumes in auto at the last SP with the baseline gains stored in the PLC (L2-5).
• Permissions reuse Forge's model: a service identity per controller with ot:tag:write on its own tags, never ot:interlock:bypass (L2-13).
  Speaker notes

  • Record §2.2, §2.3 and §2.5; the autonomy model is one mechanism for both layers (L3-5), built and audited once.

Process Control · Where It Stands

• What the tree gives it today: the OT write engine's defense chain (one tag per write, pre-read, write, read-back, audit), OPC UA to Logix, the decision models for proposals and approvals, and the one-clock rules every spoke follows: an MPC deployment is a spoke, so its FACTS time_governance declaration applies and a refused connection sheds its loops.
• Nothing of the framework is implemented, and nothing is before its FSD (WS-12, roadmap sequence item 12).
  Speaker notes

  • docs/ROADMAP.md WS-12 and D-11; docs/WHERE-WE-ARE.md §3.13. The record's §4a holds the review's facts and its [PROPOSED] answers; the owner's signature does not cover those.

F5 · Honest State

Next: how modules are built and shown.

F6 · Modules, the Module Builder and forge-display

Nav: ← F5 · ⇤ TOC · ⇅ Landing fork · F7 →

How new capability enters Forge: the language policy, the module builder's pattern, what exists in Go, the interim MES bridge and its Go rewrite, and the one UI runtime.

The Language Policy

The Module Builder Six-File Pattern

• docs/MODULE_BUILDER.md is the from-first-principles guide (~20 minutes, no prior Forge knowledge assumed): manifest, config, adapter class, context mapper, record builder, the FACTS spec, testing, CLI and API reference, common patterns, troubleshooting.
• src/forge/sdk/module_builder: manifest builder, scaffolder, generators and its CLI.
• The reference spoke is src/forge/adapters/whk_cmms (adapter, config, context, record builder, topics, entity mappers).
  Speaker notes

  • Honest: the templates are adapter-style and backend-only (FB-017), and duplicate SDK copies drift (FB-019). The Go module template does not exist yet (M3).

Go Today

The route (M3): the module SDK template in Go; forge-mes phase 1 registers, ingests and takes write-backs against the hub with the transport parity tests (FB-055) as the acceptance test; mod_mes in the hub (FB-057); changeover and MQTT in Go; parity; cut-over; the NestJS backend retired.

forge-mes · The Interim Bridge and the Go Rewrite

• The bridge's jest and tsc gates are advisory in CI (FB-048) and go away when FB-076 retires that code.
• The bridge was imported from WhiskeyHouse/whk-mes on 2026-10-15; the import's credential leak is why the repository's history was purged and the hardening of F8 exists.
  Speaker notes

  • Wording rule again: "the interim MES bridge", never "TypeScript forge-mes".

forge-display · Modules Describe, the Renderer Renders (A-3)

• A module publishes points (units, precision, ranges, staleness), alarms, actions, surfaces and the render profiles it supports; a module can only tighten the baseline, never loosen it.
• forge-display enforces nothing safety-critical itself (the core does); it ships staleness marking, bad-quality handling, ISA-101 presentation, alarm annunciation and action feedback with audit confirmation.
• Today: FVTS v0.1.0 schema, the 19-check runner, the render-profile baseline, a reference renderer, golden messages and a CI gate (FB-077). The renderer itself has no code; its open items were decided on 2026-11-03 (D-4), so its design is next (M4).
  Speaker notes

  • "Solved when": no module in the repository contains UI code, and the same FVTS spec renders on all four profiles (docs/VISION.md P-8).

F6 · Honest State

Next: how a value becomes decision-quality.

F7 · Context, Curation and Decisions

Nav: ← F6 · ⇤ TOC · ⇅ Landing fork · F8 →

From a raw value to a decision-quality figure and a recorded decision: the Context Engine, the manufacturing entities, the curation pipeline, data products with lineage, and the decision frame.

Context Is a First-Class Citizen

• A spoke's FACTS spec maps source fields to Forge context fields and declares enrichment rules; the hub fills what the source cannot: shift from timestamp, area from location, lot from the active batch.
• The Context Engine (F21) is served by the hub under /v1/context (12 routes; state changes behind context:write) with Postgres stores through the factory (FB-001, FB-005).
• The context field registry (src/forge/core/registry) is the vocabulary; RecordContext carries it slot for slot (FB-013).
• The manufacturing entity catalog (docs/core/manufacturing-entity-catalog.md) and the ISA-95 / ISA-88 hierarchy in forge.core.models.manufacturing define what context means: MaterialItem, Lot (with item_id, FB-010), ProductionOrder, equipment and areas.
• Context is never silently dropped (invariant).

Curation · From Raw Records to Data Products

• One curation engine builds each data product's pipeline from its CurationSpec (migration 010) and runs it on ingest for the published products the adapter feeds; curated records are persisted with the raw ones (FB-009).
• forge.curation: pipeline.py (multi-stage normalization and enrichment), normalization.py (field normalization, unit conversion), aggregation.py (time windows), quality.py (scoring and validation), lineage.py (provenance).
• The curation service is mounted at /curation; data products live in forge_canonical.data_products.
  Speaker notes

  • The governance frameworks that make this declarative (FQTS quality, FNTS normalization, FLTS lineage) are stubs or planned; the engine runs on the product's spec today.

Data Products

• "Solved when": every figure on a surface can be traced to its sources and transformations, and its quality objective is visible beside it (P-3).
• The same curated products are the training and evaluation sets for site-specific models, so expertise is captured where it is exercised.
  Speaker notes

  • DataProduct is a Pydantic model in forge.core.models.data_product; migration 003 mirrors it and the test suite holds the key fields.

Decisions Are Records

The research basis (docs/PRINCIPLES.md §4): decision quality degrades from incomplete information and from undisciplined judgment. Collection, governance, storage, curation and serving address the first; the decision-support layer addresses the second.

For significant decisions the 13-point minimum frame is recorded: scope, current hypothesis, supporting evidence, challenging evidence (required), alternative hypotheses, key assumptions with confidence, missing information, risk if wrong, opportunity if right, existing controls, evidence of effectiveness (required), reassessment trigger, a named owner.

• forge.core.models.decision holds the decision with the products and lineage it relied on; outcomes are observed against it (forge.observer).
• Every assumption is a tracked entity (active / validated / invalidated / superseded); new data that contradicts an active assumption alerts its owner.
  Speaker notes

  • "Solved when": a decision can be replayed: what was known, what was decided, what happened (P-9).

F7 · Honest State

Next: who may do what, and how sites keep working offline.

F8 · Security, Identity and Federation

Nav: ← F7 · ⇤ TOC · ⇅ Landing fork · F9 →

The gateway as it is, the role model as it is designed, the hub of hubs, Forge-issued credentials, and the repository's own security posture.

The Gateway Today

• "Solved when": the gateway enforces scoped roles on every route and RPC, modules hold only Forge-issued credentials, and a visibility rule such as "ERP hidden from distillery operators" is a configuration, not code (P-11).
  Speaker notes

  • Do not mistake the development default for the design: auth is off so the stack runs on a laptop; the role model below is what the gateway will enforce.

The Role Model · R-1 … R-19 (D-1 signed 2026-11-03)

Designed in dialogue in docs/decisions/roles.md; enterprise-class:

• Identity is established by the installation's chosen method (OIDC, local accounts and service identities first; then Lightweight Directory Access Protocol (LDAP)/AD; then Security Assertion Markup Language (SAML), R-10), but Forge decides what an identity may do (R-2).
• Roles are scoped (R-7), shipped per module as data (R-12), chosen in shape by the installing administrator (R-3, R-4), and constrain reads as well as actions (R-11).
• Roles are assigned at the managing hub and inherited downward (R-16); tokens verify offline against the issuing hub's public key with a one-hour default lifetime (R-8, R-15).
• Separation of duties (two-step review, interlock bypass with reason, approvals) is evaluated by the hub (R-6).
• Resolved 2026-11-03: Q21, a derived copy of assignments at the site hub, refreshed from the managing hub and never edited locally (R-18); Q22, the four-role ladder as an optional preset, off by default (R-19). FB-075, FB-078 and the multi-party approval step above FB-074 can start.
  Speaker notes

  • The record's format is the one every design record follows: status line for the owner's signature, participants, tagged statements, numbered proposals and questions.

Hub of Hubs (P-10, R-9)

• Every hub owns what is attached to it directly (spokes, child hubs, subjects) and collects, governs, stores, curates and serves that data (R-13, R-14).
• Nothing communicates through a hub; a transfer occurs at it.
• Audit records always flow upward; other data is requested on demand unless a site opts into replication (R-17).
• A site keeps working when the WAN does not: full operation for the token lifetime, audit complete on reconnection.
• The time-authority chain follows the hub hierarchy (one clock, F5).
• State: no code; milestone M6.
  Speaker notes

  • "Solved when": a site hub runs for the full token lifetime with the enterprise unreachable, and the enterprise's audit view is complete when the link returns.

Credentials and Secrets

• The hub owns the databases and issues credentials (forge db access, F3): a module never carries a database password it created itself; the password is printed once and never stored.
• Hub ↔ spoke traffic is TLS or mTLS in both directions with a per-spoke callback token.
• Configuration comes from .env files and environment variables; no credential, IP or key is hard-coded.
• gitleaks runs on every pushed commit in CI (secrets-scan) and before every push locally; nothing is imported into the repository without a history scan and a purge plan.
  Speaker notes

  • The compose stack's changeme defaults are development placeholders for the infrastructure containers, overridden by the environment; they are not Forge-issued credentials.

The Repository Security Posture (A-9)

• Lesson that binds: every import is scanned before it lands, and secrets never enter a commit; the PR workflow and the backlog rule exist in part because of this incident.
  Speaker notes

  • docs/WHERE-WE-ARE.md §3.10 carries the current state of the alerts and the support ticket.

F8 · Honest State

Next: landing a change.

F9 · Contributing

Nav: ← F8 · ⇤ TOC · ⇅ Landing fork · F10 →

Setting up, the workflow, the rules that bind, where each kind of change goes, how to add a spoke, and the governed memory that watches over the agents working here.

Set Up

git clone https://github.com/reh3376/forge.git && cd forge
uv sync --locked --extra dev --extra ot        # the same command CI and the hub image run
uv run pytest tests -q                         # 4,584 tests, ~1 minute
uv run ruff check . && uv run ruff format --check .   # both block CI; ruff is pinned exactly
(cd go && go build ./... && go vet ./... && go test ./...)
docker compose -f deploy/docker/docker-compose.yml up -d   # postgres, timescaledb, neo4j, redis, kafka, rabbitmq, minio

• Python 3.12+, uv, ruff, Docker for the services; Go 1.26 for go/; Node 20 for the interim MES bridge's CI job and Node 22 for the tutorial build.
• Every Python dependency is locked in uv.lock; --locked fails on a stale lock, so a dependency moves only through a committed re-lock (FB-096):

uv lock --upgrade-package fastapi    # one package, within its pyproject range
uv lock --upgrade                    # everything the ranges allow; then commit uv.lock

The Workflow (A-8)

• One backlog item per PR. Never push the next item onto a branch with an open PR: commit locally, push after the merge.
• The PR is opened by the workflow with the bot as author, so the owner can approve it; nobody opens PRs as the owner.
• Docs-only commits may ride along with an item; everything else is its own PR.
• Conventional Commits (feat:, fix:, docs:, build:).
  Speaker notes

  • CI runs on every push to every branch so checks attach to the commits behind auto-opened PRs; same-repo PRs do not run twice.

The Rules That Bind

Where Each Kind of Change Goes

Adding a Spoke in a Day (P-5)

1. Scaffold: the module builder generates manifest, config, adapter, context mapper, record builder and a FACTS spec skeleton (docs/MODULE_BUILDER.md §3–§4).
2. Declare: fill the FACTS spec: identity and tier, capabilities, connection, data sources with schema references, context mapping and enrichment, error handling, sample records.
3. Validate: forge governance validate-spec then forge governance run facts <spoke>; fix every violation; stamp.
4. Implement: collect, ingest, lifecycle and health in adapter.py; mappers turn source rows into ContextualRecords with the context the spec declares.
5. Test: spec tests, runner tests and adapter tests under tests/; the suite stays green.
6. Register: the hub checks the manifest against the spec at Register; with the owner's approval of the hash the spoke is live.

"Solved when": onboarding a new system is a day's work from the SDK, and a conformance failure anywhere blocks the merge, not the plant.

Testing Conventions

• tests/ mirrors src/: 267 files, 4,584 collected; the full suite runs in about a minute on the locked dependency set.
• Migration tests read the migration source and hold it to the models and writers; they do not need a database. Behavioural verification of a migration runs on a throwaway container and is recorded in the backlog row.
• Governance tests assert schema–runner parity and run every spec through its runner; FVTS has golden messages.
• The Go suite holds the Go models equal to the Python models through one shared fixture.
• Counts in README.md and docs/WHERE-WE-ARE.md are updated with every push that changes them (pytest --collect-only -q for the collected count).
  Speaker notes

  • -p no:cacheprovider keeps the repository clean of .pytest_cache; the CI job runs the same flags.

MDEMG and Jiminy · Governed Memory for the Agents

• The repository runs its own MDEMG instance (a local, graph-backed project memory) with Jiminy as the governance layer; constraints, corrections and outcomes live in the graph, not in markdown.
• The J17 handshake: identify by session, request the constraints for the task at hand, acknowledge them, act under enforcement, report the outcome.
• The PreToolUse hook enforces constraints deterministically at each tool call, whether or not the agent has read anything; a blocked action is the protocol working.
• Models: the local llama-server model mdemg-llm-v1; no cloud model, ever (A-10).
• This is problem P-7 applied to the engineering platform itself: the more AI assistance, the more the contracts and the workflow must be machine-enforced.
  Speaker notes

  • The vision counts the engineering platform as part of the product (docs/VISION.md §3.7): one item per PR, owner merges on green, findings fixed or recorded, docs current, owner-only approvals, local models, governed memory.

F9 · Recap

• uv sync --locked, pytest, ruff, go test; the compose stack for services.
• One item, docs current, gitleaks, push, auto-PR, CI green, the owner merges, fast-forward sync.
• Findings fixed or recorded; only the owner approves and signs; passwords never stored; local models only; the hook's denials are final.
• Routes get FATS specs, spokes get FACTS specs, surfaces get FVTS specs, stored shapes get migrations, owner decisions get design records.

Next: where we are and where to go.

F10 · Conclusion

Nav: ← F9 · ⇤ TOC · ⇅ Landing fork

The honest state against the vision, the milestones, the decision queue, what is next, and where to go from here.

The Largest Gaps Against the Vision

1. No forge-display: the contract and runner exist; the renderer does not.
2. No management module in Go: the interim MES bridge stands in for forge-mes; the SDK template does not exist yet.
3. No scoped roles in force: the gateway's auth is off by default; the role model is signed (D-1, 2026-11-03) and not yet enforced (FB-075).
4. No federation: a single hub only; no hub-of-hubs code.
5. Seven governance frameworks are stubs or planned; FACTS validates against its own schema and all nine of its specs carry owner-approved hashes (2026-11-13).
6. No production deployment: compose only.
7. Clock discipline declared, not yet enforced: every spoke declares how it is time-governed (FB-090) and the deployment requirement is written down, but the hub is not yet a time authority for what is attached to it and nothing refuses a wrong clock (FB-093; hub time in the contract, FB-092).
8. Process control decided, not built: the three-layer framework is signed (D-11, 2026-11-13) and waits for its FSDs.
   Speaker notes

   • docs/WHERE-WE-ARE.md §5 verbatim in substance. Each gap has backlog ids and a decision it waits on.

Milestones

The Decision Queue (owner input)

On 2026-11-03 the owner answered the open questions one at a time (34 answers) and declared the answers the signature; every gated item can start. Two standing rules came with the answers: no silent failure, and no decision that pins the platform in.

What Is Next

1. A decision session on D-1, D-3, D-4, D-8, D-9 and D-10 (done 2026-11-03, one question at a time) and the FB-076 design document (signed the same day); D-11 signed 2026-11-13.
2. The one-clock steps in the record's order: FB-088, FB-094 and FB-090 done 2026-11-13; FB-093 (fail-closed enforcement at Register and Ingest) next, then FB-092 (hub time in the contract) and FB-091 (the time-quality dimension); the one-registry steps (FB-097, D-10) before the Go module's first ingest.
3. The module SDK Go scaffold (FB-017); its first consumer is the Go forge-mes.
4. FB-076 phase 1: the Go module registers, ingests and takes write-backs against the hub.
5. FB-057 mod_mes, with FB-004 and FB-059 as the Go module needs them.
6. FB-076 phases 2–3: changeover and MQTT, parity, cut-over.
7. forge-display scaffold and renderer spike; MES surfaces first.
8. Hub platform items (FB-007, FB-075) as the Go module and forge-display start needing them.
9. Process control (D-11, WS-12): the framework FSD, then the PC-L1, PC-L2 and PC-L3 FSDs, each contract an FxTS spec before code; after the owner's round-4 answers, beside items 3 to 6.
   Speaker notes

   • docs/WHERE-WE-ARE-GOING.md §4; the detailed sequence with dependencies is docs/ROADMAP.md §4.

Where to Go Next

Thank you. Return to the landing fork ↑ · Continue to the End User path ↓

U1 · Start Here · The End User Overview

Nav: ⇤ TOC · ⇅ Landing fork · U2 →

This track is for the people who will run a Forge site or decide from it: operators, supervisors, planners, maintenance and quality staff, and the managers above them. No code. Plain language. It is complete on its own.

What Forge Is, in One Paragraph

Forge sits between the systems a plant already runs on and the people who need to decide from their data. Every system (the control system on the floor, the manufacturing execution system, the warehouse, maintenance, the ERP, the historian, scanners) connects to one hub as a spoke. Every value that crosses into the hub is checked, stamped with the hub's clock, and tagged with the context it belongs to: which site, area and equipment, which lot and work order, which shift and operator, which operating mode. From those records the hub builds data products whose figures carry their sources and a stated quality, renders the screens people use from declared contracts, and records the decisions taken on them. Forge's own modules for MES, warehouse, maintenance and the plant floor are optional: a site can keep its existing software and use Forge as the layer that connects and governs it, or replace that software one module at a time.

The Problems It Solves for You

What Forge Is Not

• Not a PLC programming environment. It reads and writes PLCs through OPC-UA; ladder logic and function blocks stay in the vendor tools.
• Not an ERP, accounting or HR system. It integrates them as spokes and may host a management module beside them; it does not replace the ledger.
• Not a cloud service. It is enterprise software installed per site and per enterprise, with local models for its own tooling.
• Not a general dashboarding product. forge-display renders Forge modules; it is not a UI framework for third parties.
  Speaker notes

  • docs/VISION.md §5.

U2 · How Data Flows

Nav: ← U1 · ⇤ TOC · ⇅ Landing fork · U3 →

1. A spoke reads from or subscribes to a plant system and sends records to the hub; the hub can also ask the spoke for data on demand, backfill history, or write back into the system.
2. The hub checks the spoke against its contract before it is allowed in, and checks every record.
3. The hub stamps when the record arrived with its own clock and measures how far the spoke's clock is from its own.
4. The record gets its context; what the source could not say (the shift from the time, the area from the location, the lot from the active batch), the hub fills in.
5. Records are stored in the store that fits them; the hub owns every database.
6. Data products are built from the records and feed screens, decisions and, where a site chooses, training data for its own models.
   Speaker notes

   • Honest: today the hub measures clock offsets and warns, and every connected system declares how it keeps time in its contract (2026-11-13); refusing a spoke whose clock is out of tolerance is decided (D-9, signed 2026-11-03) and not yet enforced (FB-093).

One Record Type

Every value that enters the hub is a contextual record:

Because every record has the same shape, "fermentation temperature of Cooker 01 during lot L-2026-0412 on the night shift" is a question the hub can answer without anyone mapping systems by hand.

One Clock

Forge exists so that people at every level decide from the same picture, and records from different sources only line up if their timestamps come from the same master time.

• The highest hub is the time authority; every hub governs the clocks of the modules and spokes attached to it; every spoke governs or measures the clocks of the systems behind it.
• Every stored timestamp is UTC with its zone; the hub stamps receipt with its own clock; the offset of every connected clock is measured and shown.
• A hub, module or spoke outside tolerance is refused: warnings are not a substitute for correction.
• For a plant-floor tag, the time that counts is when the value occurred at the device, corrected to master time, never the poll time passed off as device time.

Where it stands: timestamps are UTC and receipt is stamped; offsets are measured and warned on; on the plant floor a tag's time is corrected to the master clock by the server's measured offset (OPC UA, since 2026-11-13), no time is ever invented, and every connected system declares how it keeps time in its contract. Refusing a bad clock is decided (D-9, signed 2026-11-03) and is the next step (FB-093).

U3 · The Hub You Run

Nav: ← U2 · ⇤ TOC · ⇅ Landing fork · U4 →

What is running on a site hub, how to tell it is healthy, and the command line.

What Is Running

Today this runs from Docker Compose for development; production is a Kubernetes deployment per hub, which is not built yet (U10).

Is It Healthy?

forge health                 # the platform's own view
curl http://<hub>/v1/health  # every component: postgres, timescaledb, neo4j, redis, kafka, rabbitmq, minio
curl http://<hub>/readyz     # ready to serve?
forge adapter list           # which spokes are registered
forge adapter status <spoke> # one spoke's state, including its clock offset

• A spoke's health report includes how far its clock is from the hub's; the hub's ingest statistics show offsets per link.
• The observer (health, liveness, service-level objectives, backup status) exists as a package; its objectives and alerts are a planned framework (FOTS).
  Speaker notes

  • GET /v1/ingest/stats and OpenTelemetry metrics forge.clock.offset and forge.clock.out_of_tolerance carry the clock picture.

The Command Line

U4 · Your Systems as Spokes

Nav: ← U3 · ⇤ TOC · ⇅ Landing fork · U5 →

Which systems connect, and what the contract behind each one means to the people who depend on it.

The Connected Systems

Vendor SCADA (Ignition) runs in parallel behind a bridge while the OT module proves parity; Jython middleware scripts are being migrated to the Forge scripting SDK.

What a Contract Means to You

Each spoke has a FACTS specification: what the system is, what it is allowed to do (read, be written to, backfill, subscribe), how it connects, what data it provides, how each field maps to Forge context, and what happens on errors.

• The spec is the contract. If the spoke does not match its spec, it cannot connect.
• Approval state is visible: forge governance specs shows whether each contract is approved by the owner, pending review after a change, or modified without review.
• A change on either side fails the gate before it fails production. If a vendor upgrade changes the data a system sends, the contract check catches it in the hub, not on the floor.

U5 · The Plant Floor

Nav: ← U4 · ⇤ TOC · ⇅ Landing fork · U6 →

Tags, alarms, writes and changeover: how Forge reaches equipment, and why a screen can ask for a write but never make one.

Tags

• A tag is a named value from the floor: a temperature, a valve state, a counter. Forge reads tags through OPC-UA and keeps them in a tag engine with eight kinds of source: direct reads, scheduled polls, in-memory values, calculated expressions, SQL queries, virtual and derived values, and events.
• Every tag value carries a quality: good, bad or uncertain; a bad value is shown as bad, never as a plausible number.
• Tags carry context: the equipment and area they belong to, the lot and operating mode at the time.
• Tag paths are normalised across OPC-UA, Ignition and Forge, so a tag keeps its identity through a migration.
  Speaker notes

  • Honest: since 2026-11-13 a tag's source time on OPC UA is corrected to the master clock by the server's measured offset, with the stamp as sent and the offset kept on the record, and a value without a time is refused rather than given the poll time. Refusing a device whose clock cannot be read is the next step (FB-093).

Alarms

• Alarms follow the ISA-18.2 standard: the states above plus "suppressed by design" and "out of service"; nine alarm types (high, high-high, low, low-low, digital, rate of change, quality, communication, custom).
• Every alarm event is journaled; active alarms and history are available to screens and to other systems: an alarm can publish to the plant message bus, and a maintenance alarm can open a CMMS work order automatically.
• How alarms look (colours, sounds, priority) is the screen layer's job from a declared contract, the same on every screen.
  Speaker notes

  • src/forge/modules/ot/alarming; presentation follows ISA-101 in forge-display when it exists.

Writing to Equipment · From the Operator Seat

• A screen asks; the core decides. No path exists from any interface to a PLC that does not pass validation, review, interlocks, authorization, write with read-back, and audit.
• Some tags require two-step review: the core shows you the current value and gives you a one-time token; the commit must present the token and a reason from the site's own list.
• Interlocks block writes when a condition is unsafe; only an administrator can bypass one, with a reason that is recorded.
• Every write is reconstructible from the audit log: who, what, when, which interlocks were evaluated, what the equipment read back.
• Whether a screen may write at all depends on the kind of screen: a desktop HMI may; a web page or a phone may not.
  Speaker notes

  • Multi-party approval (two people) for certain writes is designed; the role model it needs is signed (D-1, 2026-11-03) and FB-075 builds it.

Changeover

• The OT module runs the MES changeover sequence: the recipe from the manufacturing system becomes a batch of PLC writes, each through the defense chain, driven by the CIP runner against the PLC.
• Operators confirm start, retry a recipe, resume or restart a connection through hub endpoints that require the right scope; the hub user is recorded as the actor on the MES write, the audit record and the events.
• Vendor SCADA can run in parallel during a migration: the bridge polls the vendor system and the dual-write validator proves the two agree before a cut-over.
  Speaker notes

  • Today the manufacturing system on the other side is the interim MES bridge; the Go forge-mes module takes over the changeover later.

Three Layers of Control Above the PLC

What never changes, whatever is switched on:

• You can always take over. A loop leaves MPC mode from the plant's own HMI, immediately, with Forge up or down.
• Nothing writes to a safety system, and nothing bypasses an interlock. The PLC clamps every value the upper layers write.
• No layer writes PLC code. It can recommend; an engineer decides.
• Everything starts Off. Each kind of automatic change begins as a proposal a person approves; it earns autonomy only after it has proved itself for a period you define, against figures you enter, and it loses that autonomy by itself if its record slips. If PC-L2 goes offline, PC-L3 can only write recommendations.

Where it stands: the owner decided the framework on 2026-11-13; nothing of it is built yet, and nothing will be before its specifications are written.

U6 · Context, Products and Decisions

Nav: ← U5 · ⇤ TOC · ⇅ Landing fork · U7 →

Why "area" means one thing everywhere, where a figure comes from, and how a decision is recorded so its cost can be learned.

Context · Why Area Means One Thing

• A value like TIT_2010 = 61.2 is useless until you know it is Cooker 01's temperature, in the Granary area, during lot L-2026-0412, on the night shift, in Cooking mode. Historians store values; context used to live in people's heads.
• In Forge, context is declared per spoke (which source field is the equipment, which is the lot) and defined once for the whole platform in a manufacturing entity catalogue following the ISA-95 hierarchy: enterprise, site, area, line, cell, equipment; material items, lots, production orders.
• The hub enriches what the source cannot say: the shift from the timestamp, the area from the location, the lot from the active batch.
• A record missing required context is not stored silently; what is required is declared per spoke and checked by its contract.
  Speaker notes

  • docs/core/manufacturing-entity-catalog.md; the Context Engine serves the vocabulary under /v1/context.

Data Products · Where a Figure Comes From

Normalisation happens before comparison: units are converted, time is aligned, and a comparison declares its basis or says "unnormalised". Aggregate views link to the segmented views beneath them, so a trend cannot hide the operating condition that explains it.

Recording a Decision

A confidently wrong decision costs more than the data problem that caused it, and its cost is spread across many shifts and units. Forge treats the decision as a record.

For significant decisions (capital allocation, process changes, root-cause conclusions, vendor selection, quality dispositions) the system records a minimum frame: what is being decided and why now; the current hypothesis with evidence links; challenging evidence, required; alternative hypotheses; key assumptions with a confidence; missing information; risk if wrong; opportunity if right; existing controls and evidence they work, required; a reassessment trigger; and a named owner.

• Every assumption is tracked; new data that contradicts one alerts its owner and the owners of every decision that relied on it.
• Outcomes are observed against the decision, so what was known, what was decided and what happened can be replayed.

Where it stands: the decision and assumption models exist in the hub; the decision-support workflow around them is not built yet.

U7 · Governance for Users

Nav: ← U6 · ⇤ TOC · ⇅ Landing fork · U8 →

What "approved" means, why nothing changes silently, and the owner's role.

Contracts, Not Promises

• Every interface in Forge is a specification: what a spoke may do, what a hub route returns, what a screen shows and which action needs which role, how transport is secured.
• The specification is checked by a runner and enforced as a gate: a change that breaks a contract is stopped before it is merged, not discovered on the floor.
• Specifications are hashed. Each carries its hash, its state and a history of who or what changed it.

• Only the owner approves. AI coding agents working on the platform can propose and stamp; they can never approve, and the hub checks the hash before trusting a contract.
  Speaker notes

  • docs/FxTS/README.md and docs/PRINCIPLES.md §3; the command is forge governance specs --pending.

Why This Matters to You

• A spoke whose contract was relaxed without approval cannot register.
• A route that stopped returning what its contract says fails the build.
• A screen that tries to write from a profile that may not fails the view contract.
• The platform's own engineering is governed the same way: one item per change, every finding recorded, documents current before every change ships, owner-only approvals, and a governed memory for the AI agents that work on the code.
  Speaker notes

  • Problem P-7 in docs/VISION.md: the more AI assistance a team uses, the more the contracts must be machine-enforced.

U8 · Screens

Nav: ← U7 · ⇤ TOC · ⇅ Landing fork · U9 →

What you will look at, and what you look at today.

One Renderer, Four Kinds of Screen

In the finished system no module ships its own screens. A module describes what it has (points with units and ranges, alarms, actions with the role and confirmation each needs, surfaces) and forge-display renders it on four profiles:

• A module may make a screen stricter than the baseline, never looser.
• Stale values are marked, bad quality is shown, alarms are annunciated and styled by one standard (ISA-101), and every action shows its result with the audit confirmation.
  Speaker notes

  • docs/VISION.md P-8 and §3.4; the contract is FVTS.

What You Look at Today · Honest

• forge-display does not exist yet. Its contract (FVTS), the checker, a render-profile baseline, a reference renderer and example messages do; its open questions were answered by the owner on 2026-11-03 (D-4), so the renderer's design is next.
• The manufacturing system's screens today are the interim MES bridge's own web frontend, imported with it; they will be retired when forge-display renders the MES surfaces.
• Plant-floor screens today are the vendor's (Ignition) where a site keeps them; the OT module serves the data behind them and its REST interfaces.
  Speaker notes

  • Milestone M4 is the renderer; MES surfaces first, then the OT HMI surfaces.

U9 · Identity, Roles and Credentials

Nav: ← U8 · ⇤ TOC · ⇅ Landing fork · U10 →

Who may do what, where, and how systems get their credentials.

Identity and Roles

• Your installation chooses how people sign in (single sign-on with OpenID Connect, local accounts, LDAP or Active Directory, SAML), and Forge decides what a signed-in identity may do.
• Roles are scoped: a role says what you may do in which area, on which equipment, in which module. "Operators in the distillery may acknowledge alarms there and see nothing from the ERP" is a configuration, not a program.
• Roles constrain what you can read as well as what you can do.
• Separation of duties is evaluated by the hub: two-step review on a write, an interlock bypass with a recorded reason, approvals.
• In a multi-site enterprise, roles are assigned at the managing hub and inherited by sites; a site keeps verifying sign-ins while the link to headquarters is down.

Where it stands: the role model is decided and signed (2026-11-03); the hub's authentication is off by default in development, and scoped roles on every route are not yet enforced (FB-075).

Credentials

• The hub owns the databases. A module never carries a database password it created itself: the hub grants a module access to its own schema and hands it a credential that is printed once and never stored; re-issuing rotates it.
• Hub ↔ spoke traffic is encrypted both ways with certificates, and each spoke has its own token.
• Every grant, every issued credential and every refusal is in the hub's access audit.
  Speaker notes

  • forge db access in U3; the design is docs/DB_ORCHESTRATION_FRAMEWORK.md.

U10 · Operations

Nav: ← U9 · ⇤ TOC · ⇅ Landing fork · U11 →

How a site is run, upgraded and, in time, backed up.

Running a Site · Honest

• "Solved when": a site hub can be stood up, upgraded and restored from backup by procedure, and its objectives are visible.
  Speaker notes

  • docs/WHERE-WE-ARE.md §3.11; the K8s decision is recorded as owner's note.

U11 · Where to Go Next

Nav: ← U10 · ⇤ TOC · ⇅ Landing fork

Thank you. Return to the landing fork ↑ · Start the Software Dev path ↑