4995456136
The publishability gate caught internal tooling names and developer paths but nothing site-specific, so roughly sixty leaks reached the wiki: the site name in ten documents, real fleet hostnames in the collector and GE-Enforce examples, an internal database name through the whole import guide, imaging-share paths, and a maintainer's username as the Deciders line of every ADR and inside a generated curl example. None of it is a security matter on an air-gapped fleet. It matters because these pages are read by engineers at other plants, and a document that names one site throughout reads as that site's notes rather than a product's documentation - which is exactly what it then gets treated as. Examples now use neutral hostnames, the site is "the reference site" where the distinction carries meaning, and ADRs are decided by "ShopDB maintainers". The gate carries all of these patterns, so the next one fails a build. Two documents leave docs/ because they were never written for an outside reader. PROJECT-REVIEW.md is an internal health memo pinned to a commit from July, whose headline finding (an untracked playbook) has since been fixed - it is history, and git holds it. PILOT-DEPLOY.md is one site's own cutover runbook, complete with a "re-measure before publishing" placeholder; it moves next to the loader it belongs to, in scripts/site_imports/wjf/. ADR-015 is AMENDED rather than rewritten. Its enforcement section still said report-only and its backlog still listed hardcodes that are now cleared, which left the record contradicting itself. The amendment says what changed and why the report-only period ended; the original text stays, because what the decision looked like when it was taken is the part worth keeping. Also corrects llms.txt's response envelope, which had errors at the top level and pagination at meta.total. Both are nested one deeper, so anything written against that description read undefined on every error it tried to handle.
124 lines
6.9 KiB
Markdown
124 lines
6.9 KiB
Markdown
# ADR-012: GE-Enforce manifest ownership in shopdb
|
|
|
|
- **Status:** ACCEPTED
|
|
- **Date:** 2026-07-13
|
|
- **Deciders:** ShopDB maintainers
|
|
- **Relates to:** ADR-002 (plugin contract versioning), ADR-004 (per-site
|
|
deployment), ADR-006 (collector contract), ADR-008 (per-plugin Alembic chains)
|
|
|
|
## Context
|
|
|
|
GE-Enforce is a desired-state enforcement system for shopfloor PCs: a PowerShell
|
|
engine (`Install-FromManifest.ps1`) reads per-PC-type `manifest.json` files off
|
|
an SMB share every logon and installs / self-heals what they declare. Authoring
|
|
those manifests today means hand-editing JSON on a file share, and there is no
|
|
central view of what each PC actually did.
|
|
|
|
We want shopdb to own the manifests as data (author, version, publish, roll
|
|
back) and to observe fleet compliance, while NOT taking on the GE-Enforce engine
|
|
itself (which is the GE-Enforce framework's, maintained separately) and NOT
|
|
dictating any site's imaging path (per ADR-004, each site is single-tenant with
|
|
its own provisioning - PXE at the reference site, OOBE provisioning packages at
|
|
others).
|
|
|
|
The manifests are an enforcement PROGRAM, not an application inventory: entry
|
|
`Type` is not an app/config discriminator and entry `Name` is a manifest label,
|
|
not a Windows ARP DisplayName. Any design that treats them as an app catalog is
|
|
wrong.
|
|
|
|
## Decision
|
|
|
|
Build a bundled `geenforce` plugin that owns the manifest as shopdb data, with a
|
|
client kit and a deployment bootstrap. Specifically:
|
|
|
|
1. **Data model.** One wide `manifestentries` table with an `entrytype`
|
|
discriminator and nullable per-type columns (not SQLAlchemy STI, not a JSON
|
|
blob - the fleet is ~64 entries, so sparse columns are free and stay
|
|
queryable). Scopes are `manifestscopes`, unique on `(scopename, phase)`;
|
|
runtime is per-pctype scopes, preinstall is one flat scope. Multi-value gates
|
|
(PCTypes / hostnames / machine numbers) and the nested InUseCheck are child
|
|
tables. `sortorder` is the execution-order contract. RegValue is stored as a
|
|
raw JSON literal so DWord-vs-string typing survives. Per-plugin Alembic chain
|
|
(ADR-008).
|
|
|
|
2. **Published snapshots.** Editing touches a DRAFT only. Publish freezes the
|
|
rendered JSON document into an immutable `manifestpublishedversions` row; the
|
|
client is ALWAYS served the current published snapshot, never the draft;
|
|
rollback flips `iscurrent` to an older version. Freezing the document (not
|
|
row-mirroring) makes immutability structural.
|
|
|
|
3. **Behavioral-parity gate, not byte-identity.** A DB-free harness
|
|
(`parity.py`) imports each real manifest and renders it back, then proves
|
|
BEHAVIORAL equivalence (same ordered entries with identical detection /
|
|
targeting, and the same entries fire across machine-profile fixtures) - never
|
|
byte equality, which re-serialization would never satisfy. This gates any
|
|
build that touches the model.
|
|
|
|
4. **Filter mirror; engine is the single source of truth.** `filters.py`
|
|
mirrors the engine's four gate functions and alias graph for the "what would
|
|
this PC get" simulator and parity. The engine lib stays authoritative;
|
|
shopdb mirrors it (never the reverse). PCTypesStrict is honored only for the
|
|
preinstall phase, matching the runners.
|
|
|
|
5. **Payload integrity is separate from detection.** For `http`/`inline`
|
|
payloads a dedicated `payloadsha256` is verified before running - independent
|
|
of `DetectionMethod` (DetectionValue is a hash only for `Hash` detection).
|
|
`smb` payloads keep the share ACL as their trust boundary. Large binaries
|
|
stay on SMB; small config/scripts may move to http/inline later.
|
|
|
|
6. **Observed-state reporting.** Each PC POSTs its enforcement result;
|
|
`manifestenforcementreports` (+ results) records the applied version
|
|
(received-latest) and per-entry self-heal / failure. Status derives from
|
|
explicit self-heal flags only, never the raw installed count (Always/no-
|
|
detection scripts install every cycle without being drift corrections).
|
|
|
|
7. **Service-token auth.** Client endpoints authorize via managed service
|
|
tokens scoped `geenforce.fetch` / `geenforce.report`, through a new
|
|
`service_token_authorized(scope)` on the `shopdb.api` contract surface
|
|
(contract 0.11.0). Admin CRUD uses `geenforce.manage` / `geenforce.publish`.
|
|
|
|
8. **Client + deployment, engine referenced not vendored.** shopdb ships the
|
|
fetch/report kit (`plugins/geenforce/client/`) and a site-neutral bootstrap
|
|
(`Install-GEEnforce.ps1`) that provisions a PC's identity
|
|
(`C:\Enrollment\pc-type.txt` etc. - what determines the PC type; there is no
|
|
auto-detection, the provisioner supplies it), the shopdb registry config, and
|
|
the scheduled task. The GE-Enforce ENGINE is referenced (`-EngineSource`),
|
|
not carried by shopdb. Deployment is provisioning-path independent (PXE step,
|
|
OOBE ppkg, Intune, manual); the runtime task is fail-safe.
|
|
|
|
9. **Milestone 1 = export to share; staged cutover.** Until a site cuts its
|
|
client over to shopdb-sourced manifests, the plugin publishes and EXPORTS the
|
|
manifest to the share (with a `_meta/history` backup, atomic write); the
|
|
unchanged engine picks it up. Cutover is staged: shadow mode (fetch from
|
|
shopdb AND read the share, log diffs, install from share) then read cutover.
|
|
|
|
10. **No application auto-seeding.** The core Applications catalog already
|
|
tracks these apps (from the classic-shopdb migration) with version
|
|
histories; auto-creating Applications from manifest labels produced
|
|
duplicates and misclassified config drops. Application linkage, if wanted, is
|
|
a curated manifest-entry -> existing-Application link, not label scraping.
|
|
|
|
## Consequences
|
|
|
|
- **Positive.** Manifests become validated, versioned, publishable data with
|
|
one-click rollback and a fleet-compliance view; desired-state and observed-
|
|
state live in one system. The parity gate + published snapshots + separate
|
|
payload hash make a fleet-wide-SYSTEM system safe to author. The plugin is
|
|
provisioning-agnostic, so any GE Aerospace site can adopt it regardless of
|
|
imaging path. Validated end to end: parity green against the real manifests,
|
|
and the client kit + installer proven on a Windows VM (PS 5.1) and Linux
|
|
pwsh 7.
|
|
- **Boundaries / risks.** The engine remains the GE-Enforce framework's, so
|
|
shopdb's parity mirror must be kept in sync with the lib (guarded by the parity
|
|
fixtures; the plugin pins lib >= 2.6 for `_CmmVersion`). Provisioning writes
|
|
the PC identity - shopdb cannot set a PC's type at imaging (a PC is unknown
|
|
until it enrolls and reports). Manifest-label vs ARP-name mismatch means the
|
|
catalog link, when built, needs a curated alias layer.
|
|
- **Deferred.** Desired-vs-observed per-entry compliance (needs a collector
|
|
installedVersions field); curated manifest-entry -> Application linking; the
|
|
live client cutover (a site operational decision); inline payload upload.
|
|
|
|
See `docs/proposals/ge-enforce-plugin.md` (design + cutover), `docs/GE-ENFORCE.md`
|
|
(concepts + imaging timeline), `docs/GE-ENFORCE-CLIENT.md` (fetch/report
|
|
contract), and `docs/GE-ENFORCE-DEPLOY.md` (agent deployment).
|