534f179ee6
main was 16 days and 259 commits behind the line the product is actually built on, at contract 0.30.0 against 0.35.0, with no per-PC credential code at all. It was neither current nor curated - just stale. This brings it forward and, at the same time, makes it mean something: main is what a receiving site installs, and nothing else. WHAT IT CARRIES. Twelve plugins - backups, computers, endpoints, guides, knowledgebase, machines, network, notifications, printers, slides, tools, warranty - plus applications, which is manifest-less core and always ships. The only manifest dependency inside that set is endpoints on computers, and both are in it, so the closure is self-contained. WHAT IT DOES NOT. employees, geenforce, measuringtools, printedparts and usb stay on the site line. So do the Windows installer tree, the VM rehearsal helpers, the agent tooling config, one site's data loader, the internal audit and findings records, and the planner spreadsheet. 1,135 tracked files against 1,438. A REMOVAL THAT BREAKS THE APP IS NOT A REMOVAL, and two nearly shipped: deploy/site-profile-universal.json still named all seventeen plugins. It is the file docs/DEPLOY.md tells a site to provision from, so a fresh install would have failed at `flask plugin apply-profile` with PluginError - the first thing a receiving site does, broken by the branch meant to serve them. It now names the twelve that exist, and its comment says the two must agree. agent/ was never refreshed. Whoever populated this branch copied shopdb/, plugins/, frontend/ and tests/ from the site line and left the agent tree at its September state: 22 C# and PowerShell sources missing, including AgentCredentials, EnrollmentService, AgentHttpFactory and the fleet-alert client, plus one file the site line had deleted still present. The old tree is internally consistent, so it compiles, and nothing in CI builds it - every gate was green over a server that speaks enrollment and per-PC credentials to a bundled agent source that cannot. Resynced whole. DECISIONS THIS ENCODES, rather than defers: - The plugin-authoring lab builds printedparts, whose manifest depends on employees, so it could not stay. The lab remains on the site line and main ships no build-along tutorial. That is a real loss for an adopting developer and is recorded here rather than discovered later. - Recognition, Training and Recertification notifications are no longer seeded. Each splits one notification into a card per employee and renders a photo, which needs a plugin this branch does not bundle. Seeding them would offer an author a type that cannot resolve anybody. A site that installs employees gets them from that plugin's own seed. - Windows/IIS is documented as the legacy path throughout, and the README leads with Docker, because that is what a receiving site gets. The API description is regenerated for THIS branch - 347 paths and 483 operations, down from 415 and 573 - so the published contract describes what is here rather than what the site line serves. docs/CONFIG.md lost the two measuring-tool label keys the code no longer declares, which two lanes had decided opposite ways. Suite: 3124 passed, 6 skipped. Naming and style gates pass. The docs gates run rather than skip, and every index line count is derived from the file it names.
138 lines
7.5 KiB
Markdown
138 lines
7.5 KiB
Markdown
<!-- docmeta
|
|
purpose: explanation
|
|
audience: developer, adopter
|
|
status: historical
|
|
summary: The record of why ShopDB owned GE-Enforce manifests as data. The plugin it decided is not bundled here.
|
|
loadwith: none
|
|
-->
|
|
|
|
# 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)
|
|
|
|
> **Not bundled on this line.** The `geenforce` plugin this ADR decided is not
|
|
> part of this product build, so nothing here is a procedure to follow. It is
|
|
> kept because it is a decision record and because ADR-013 and the resource-scope
|
|
> design on API tokens both trace back to it. The plugin, its client and its
|
|
> pages live on the site line that still runs them.
|
|
|
|
## 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.
|
|
|
|
The design note, the concepts page, the fetch/report contract and the client
|
|
deployment page were all written against this plugin and stay with it on the
|
|
site line that carries it. None of them is in this repository.
|