factory-line-audit 0.1.0__tar.gz

factory_line_audit-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

factory_line_audit-0.1.0/NOTICE

@@ -0,0 +1,41 @@
+factory-line-audit
+Copyright 2026 The Arbiter Project Authors
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied.
+
+This project reads a discrete-manufacturing line over OPC UA. It is not
+affiliated with, endorsed by, or part of the OPC Foundation, and `OPC UA` is
+their trademark rather than anything claimed here.
+
+NO REDISTRIBUTED THIRD-PARTY CONTENT
+
+Nothing in this repository was copied from anywhere else. `examples/` is
+invented in full and says so on its face: every `basis` string in the
+declaration fixture begins `FIXTURE`, and the review gate passes that file only
+because it discloses itself. No number here is a fact about a real machine, and
+no register here was exported from a real plant.
+
+`battery/corpus/` is generated by `battery/make_corpus.py` and is not committed.
+It expires: several of the engine's arms count inside a window measured
+backwards from now, so a committed copy would be stale on arrival.
+
+DEPENDENCIES, SEPARATELY LICENSED
+
+At Stage 2 this project depends on `arbiter-engine`, and the optional vertical
+registration depends on `presence-audit`. Both are separately licensed under the
+same terms. This is a consumer of them and not a part of either.
+
+Stage 1 -- presence, the declarations channel, its gate, and model generation --
+depends on nothing at all, and that is asserted by a test rather than promised
+here.
+
+The method this bridge was built to is `BRIDGES.md` in the `arbiter-engine`
+repository. `FINDINGS.md` reports where following it produced a wrong answer.

factory_line_audit-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: factory-line-audit
+Version: 0.1.0
+Summary: A bridge from a discrete-manufacturing line to arbiter-engine
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: detect
+Requires-Dist: arbiter-engine<0.2,>=0.1.10; extra == "detect"
+Provides-Extra: live
+Requires-Dist: asyncua<3,>=1.0; extra == "live"
+Provides-Extra: vertical
+Requires-Dist: presence-audit<0.2,>=0.1.6; extra == "vertical"
+Dynamic: license-file
+
+# factory-line-audit
+
+A bridge from a discrete-manufacturing line to
+[`arbiter-engine`](https://github.com/james-sheen/arbiter), 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](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.0**, tagged `v0.1.0`, Apache-2.0, on PyPI as
+[`factory-line-audit`](https://pypi.org/project/factory-line-audit/).
+
+**Status: a live-but-safe surface read for real -- the third of the four rungs
+named below.** Thirteen battery legs green against
+`arbiter-engine 0.1.10` from PyPI, including a real OPC UA server read by a real
+client and the built wheel installed into an empty environment. 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}
+```
+
+## 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](FINDINGS.md).
+
+## 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:
+
+```bash
+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
+
+Sixteen legs: the twelve in `BRIDGES.md`'s verification battery, plus four added
+with the argument written down.
+
+All five additions 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` and `capture` still are.
+
+| Leg | Question |
+|---|---|
+| `corpus` **added** | Is the corpus still inside the narrowest measured window? |
+| `live` | Can a live OPC UA surface be read at all, and how many nodes did it serve? |
+| `capture` **added** | Does the shipped verb print one OUTCOME line, a handle `sha256sum` agrees with, and a membership cache holding no reading? |
+| `draft` | Does draft tooling emit an unreviewed statement and exit clean? |
+| `gate` | Does the gate then refuse that exact file, by name? |
+| `clean` | Over an uncontaminated corpus, does the pipeline stay quiet? |
+| `fault` | For each of thirteen fault classes, is the injected thing found? |
+| `absent` | Is a declared-but-absent source a finding, not an incompleteness? |
+| `attest` | Does attestation work through the same front door? |
+| `pipe` | Does a reader walking away change the verdict, or print anything? |
+| `tool` | Is the tool surface closed, and does every entry construct? |
+| `suite` | Does the suite pass from a directory that is not the repository? |
+| `conformance` **added** | Does the core's own kit still accept this vertical, and does its noun reach the core? |
+| `regression` **added** | Does a declared prefix move pair, and the same move undeclared get reported and not applied? |
+| `pin` | Does every release inside each declared range actually run? |
+| `ship` | Does the built artifact, installed clean, still do all of that? |
+
+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.
+
+Most of the battery is run by hand, because it builds a wheel and installs
+every release in two ranges. Three legs are the exception and run in CI:
+`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` on one, because the OPC UA surface is anonymous,
+localhost and over in seconds, and `capture` is the only verb here that talks
+to anything. `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.
+
+| Format | What it is |
+|---|---|
+| `factory-line-audit/register/1` | What should exist: assets, tags with a declared `class` and node id, typed relations |
+| `factory-line-audit/walk/1` | What the server served, with per-reading status word and source timestamp |
+| `factory-line-audit/presence/1` | Stage 1's three-way classification |
+| `factory-line-audit/declaration/1` | Operator statements, each with a `basis`, and a review marker |
+| `factory-line-audit/manifest/1` | Everything excluded from the model with a reason, the entity-type map, and every indicator this package derived |
+| `factory-line-audit/attest/1` | Per-run record: checked, declined, not-established, engine strings verbatim, exit |
+
+## 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`, `redundant`, `conservation`,
+`expect_variation`, `slow_oscillation`, `gate_on`, `exclusion`. Each maps onto
+exactly one thing the engine would otherwise decline, which is the decline
+vocabulary read backwards.
+
+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.
+
+## The evidence ladder
+
+| Rung | What it is | Here |
+|---|---|---|
+| 1 | Synthetic corpus | `battery/corpus/clean.json`, sized from measured floors |
+| 2 | Mutated copies | thirteen one-fault copies with expectations declared before the run |
+| 3 | A live-but-safe surface | `battery/opcua_surface.py` -- a real server, a real client, localhost |
+| 4 | First contact | **not climbed.** A person, a plant, a register exported from that plant's MES, declarations signed by that plant's engineers |
+
+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 `0.1.10` from PyPI, and `0.1.11.dev0` from `master` was
+  run too. Any other pin needs `probe_engine.py` re-run, not re-read.
+- 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.