factory-line-audit

A bridge from a discrete-manufacturing line to arbiter-engine, built to the method in that repository's BRIDGES.md against nothing but its published surfaces.

The engine and this bridge share an author. So the exam below is a deliberate self-exam, not the independent adoption BRIDGES.md asks for, and this sentence used to say otherwise. What the findings rest on is the method rather than the distance: the bridge was written from the published document and the released package, and every claim names the probe that produced it. Read them as a first pass by someone holding every advantage.

The engine judges series and properties it is handed and refuses to invent a fact to fill a gap. Everything it refuses to own -- what exists on the line, what each tag is, what is deliberately not watched, what only an operator can know, what gets fed and when, and how a verdict becomes an exit code -- is here.

Its purpose is twofold. It is a working audit tool for a cell of stations, presses, robots and controllers read over OPC UA. It is also an exam of the method: BRIDGES.md invites the first vertical that shares no vocabulary with its worked examples to report the parts that do not survive contact. FINDINGS.md is that report: findings against the method, findings against the engine and its modelling guide, and both of the findings the previous attempt at this bridge left to be filed upstream, withdrawn because re-measurement did not reproduce them.

Released -- 0.1.7, tagged v0.1.7, Apache-2.0, on PyPI as factory-line-audit.

Status: a live-but-safe surface read for real -- the third of the four rungs named below. Eighteen battery legs green, including a real OPC UA server read by a real client, the built wheel installed into an empty environment, and a sweep of the whole arbiter-engine range this package declares. Nothing here has touched a plant. Every number in examples/ is invented.

The two stages

Stage 1 -- presence. Given a register of what should exist and a walk of what the server served, classify every declared tag three ways: reading, present but not reading, absent. This has no dependencies at all, and asserting that is a test rather than a promise.

Stage 2 -- detection. Generate a model and a manifest from the register plus reviewed operator declarations, feed only what Stage 1 saw reading, and turn the engine's envelope into an exit code, an attestation and a human report.

register.json ─┬─> presence ──> presence/1
               │       │
declarations ──┤       └────────┐  (only reading tags are fed)
   (gated)     │                v
               └─> generate ──> model.yaml + manifest/1 ──> detect ──> attest/1
                                                                        exit {0,1,2}

The verbs

Nine, and the page names all nine because a verb nobody documents is a verb nobody runs.

• presence -- Stage 1: what the register declares against what the walk served, classified three ways. No dependencies.
• validate-walk -- everything wrong with a walk file, or nothing. A receiver checking a file: no engine, no core, no server. A malformed walk is could not complete, never a finding, because a file that would not read is not a finding about the line.
• draft -- propose the declarations a person would have to make, every basis empty and every number null. Exits clean; gate refuses what it wrote.
• gate -- refuse unreviewed declarations, naming the file.
• generate -- the model and the manifest, as a pair.
• detect -- Stage 2: feed the engine what Stage 1 saw reading, report, and exit on the contract above.
• attest -- re-report a stored attestation through the same front door, and reach the same verdict.
• capture -- read a live OPC UA server and write a walk.
• regression -- two walks of one line, oldest first. An undeclared prefix shift is reported, never applied.

Exit codes

0 clean, 1 findings, 2 could-not-complete. 2 never reads as clean and 2 beats 1. Composed as the maximum over every leg, with each floor decided at design time in exit_contract.py -- including, unusually, floors for findings as well as declines. The reason is measured and is in FINDINGS.md A3.

Quick start

To use it: pip install 'factory-line-audit[detect,live]'. To work on it, or to run the verification battery below, take a checkout instead:

git clone https://github.com/james-sheen/factory-line-audit
cd factory-line-audit
python3 -m virtualenv /tmp/v && /tmp/v/bin/pip install -e '.[detect,live]'
export PYTHONPATH=src

# C3 -- measure the engine you pinned. Everything else derives from this.
/tmp/v/bin/python battery/probe_engine.py

# the corpus, sized from those floors and stamped at build time
python3 battery/make_corpus.py

# Stage 1, with the engine uninstalled if you like
python3 -m factory_line_audit.cli presence \
    --register examples/asset_register.json --walk battery/corpus/clean.json

# the channel and its gate
python3 -m factory_line_audit.cli draft --register examples/asset_register.json --out /tmp/d.json   # 0
python3 -m factory_line_audit.cli gate  --register examples/asset_register.json /tmp/d.json         # 2, names it
python3 -m factory_line_audit.cli gate  --register examples/asset_register.json \
    examples/declarations/line1.fixture.json                                                        # 0

# Stage 2
/tmp/v/bin/python -m factory_line_audit.cli detect \
    --register examples/asset_register.json --walk battery/corpus/clean.json \
    --declarations examples/declarations/line1.fixture.json --attest-out /tmp/attest.json

# C8 -- exercise both declared ranges, floors included (installs each release; slow)
python3 battery/probe_pin.py

# does the core still accept this vertical? two imports, and CI runs it too
/tmp/v/bin/python battery/probe_conformance.py

# the whole battery
/tmp/v/bin/python battery/run_battery.py --python /tmp/v/bin/python --live-python /tmp/v/bin/python

The verification battery

Eighteen legs: the twelve in BRIDGES.md's verification battery, plus the ones this package added, each with the argument written down.

Every addition started here. pin was proposed by this package and is now a row in the guide's own table, so it is no longer an addition and is unmarked below. corpus, conformance, regression, capture, engine and orchestrator still are.

A leg that could not run reports 2 and is named, never skipped. --only NAME runs a subset; a name no leg carries is refused rather than answered with an empty run, and the result file records the selection so a partial run cannot read as a full one.

The whole battery runs in CI, on every push, in under a minute. It is that cheap because pin reads the evidence probe_pin.py wrote rather than sweeping: the sweep installs every release in two ranges and runs weekly in its own workflow. Three legs also run a second time on their own terms, and the duplication is the point: conformance on every interpreter, because it costs two imports and is the only leg whose question is about software this package does not control; and live and capture in a job that installs the OPC UA client and nothing else, which is the only way either can say capture needs no axiom engine to read a server. probe_status_words.py runs beside them: it grades every status word asyncua can report, which is the population a real PLC draws from rather than the three the corpus happens to carry. A leg nothing triggers is a leg nobody reads, which is the same argument the legs themselves are written from.

Formats

All JSON, all carrying a format string, all refusing an unknown major by name.

Declarations

A rule can propose an operator-knowledge fact. It cannot know one. Every statement carries a basis -- what the declarer actually looked at -- and draft emits them unreviewed with every basis empty and every number null, because the one thing a rule cannot supply is why.

Kinds: bound, setpoint, rate, reset, redundant, conservation, expect_variation, slow_oscillation, gate_on, bad_state, exclusion. Each maps onto exactly one thing the engine would otherwise decline, which is the decline vocabulary read backwards -- except reset, which answers something the engine never declines: it routes a counter that drops to zero from its own default and says nothing about having done so.

A file becomes usable when a person adds their name and the date. A test fixture passes only by disclosing itself on its face, never by naming a reviewer.

Upgrading, if you keep declaration files. Three refusals arrived in 0.1.6 and 0.1.7, each replacing something that was accepted and then ignored.

• allow_reset is a reset statement of its own (0.1.6). It used to be read off a rate statement and validated by nothing, so a misspelling read as a declaration while the engine routed from its own default. A rate statement still carrying it is refused by name, pointing at where it moved. A counter with no reset statement is recorded in the manifest as running on the engine's routing -- a line in a report, not an error.
• gate_on takes open_when, a list of the state WORDS that mean the check applies (0.1.7). The gate read bool(value), and every non-empty word a PLC produces is true in Python -- so a station reporting Stopped opened the gate and the run judged a takt the station was not running to. Where the state is not a boolean and no open_when is declared, detect stops rather than guesses. required_property must also name a state-class tag on the same asset.
• A statement declared twice is refused (0.1.7), across every accepted file. The generator reads the first of each kind, so the second was accepted and ignored -- and across two files the earlier file won, an ordering nobody declared. An exclusion naming a tag the register does not have is refused for the same reason: it excluded nothing and was recorded as an exclusion.

The evidence ladder

Rung 3 is evidence that the walk format survives a real client, that node ids resolve, that a status word comes back as a status word, and that a node which is not there fails the way Stage 1 says it does. It is not evidence about security, certificates, a vendor's address space, or load.

First contact is deliberately absent from the tool surface as well, and the closure test asserts that absence.

What this package does not claim

• No number in examples/ is a fact about a real machine. The declaration file says so on its face and every basis string begins FIXTURE.
• The engine measured is whichever one battery/engine_floors.json records, and the engine battery leg goes red when that file stops describing the engine that resolves here. Any other pin needs probe_engine.py re-run, not re-read. This line named a version until 2026-09-09, by which time the file recorded a later one.
• Ten of the twelve decline reasons are reachable from a model this package could generate. not_applicable and checker_error are engine-side.
• The learned-baseline warning arm has a measured false-positive rate of roughly one series in twelve. It is reported in full and floored at 0, and that is a judgement, written down in exit_contract.py with the measurement behind it.

Security reports go through SECURITY.md, privately -- for the failure modes listed there, filing the report in public is the disclosure. CONTRIBUTING.md has the one thing a fresh clone will not tell you: the hooks are per-clone and off until you enable them.