ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
62c5454f00eba0d724f94dea8bf18b39beb689af
shopdb-flask/docs/adr/ADR-012-geenforce-manifest-ownership.md
cproudlock 4995456136 docs: take one site's name, hosts and paths off the public wiki 
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.
2026-08-14 15:38:27 -04:00

6.9 KiB
Raw Blame History

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).

Reference in New Issue View Git Blame Copy Permalink