ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: ADR 012 geenforce manifest ownership
Pages
ADR 001 asset as platform contract ADR 002 plugin versioning ADR 003 plugin distribution ADR 004 deployment topology ADR 005 equipment vs measuringtools ADR 006 collector contract ADR 007 product versioning and releases ADR 008 plugin migration ownership ADR 009 frontend plugin gating ADR 010 frontend plugin hooks ADR 011 machines rename ADR 012 geenforce manifest ownership BACKUP RESTORE COLLECTOR INTEGRATION CONFIG CONTRACT STABILITY DEPLOY WINDOWS IIS DEPLOY GE ENFORCE CLIENT GE ENFORCE DEPLOY GE ENFORCE Home IMPORT ADOPTION IMPORT API INSTALL WINDOWS IIS PILOT DEPLOY PLUGIN EXTERNAL REPO PLUGIN GUIDE PLUGIN HOOKS PLUGIN QUICKSTART PLUGINS PROPOSAL ge enforce plugin README ROADMAP UPGRADE
Clone
1
ADR 012 geenforce manifest ownership
Cameron Proudlock edited this page 2026-07-13 19:51:21 -04:00
Table of Contents

ADR-012: GE-Enforce manifest ownership in shopdb

  • Status: ACCEPTED
  • Date: 2026-07-13
  • Deciders: cproudlock
  • 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 West Jefferson, 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).

Docs

Install and operate

Data import

Plugins

Integrations

Project

ADRs

Proposals