Wave one of the dashboard proposal, built as a vertical slice so the contract
is proven by something real before the other five cards follow.
GET /api/geenforce/dashboard/failures lists entries that FAILED on their PC's
most recent enforcement cycle. Per ENTRY, not per report: "three PCs failed" is
a number, while "Install OpenText failed with exit 1603 on WJSF1234" is
something a person can act on. Only current reports count, so a failure that
has since been fixed clears itself instead of needing dismissing. Hostnames
resolve to computerids in one query so each row links to the PC, and a PC
shopdb does not know still appears - the failure is real even when the
inventory is behind, and that is the bay most likely to be misconfigured.
The data has been there all along. The only way to see any of it was to open
one PC's report modal, one PC at a time.
The widget declaration is the contract change. The old shape named a Vue
component per widget, which cannot survive a lean build where a plugin's
component may never be staged into the bundle - which is exactly why five
plugins declare widgets pointing at components nobody ever wrote. This declares
data, a generic renderer, a permission and a link template, the way ADR-010
already does for asset panels. A test asserts no 'component' key, so the old
shape cannot creep back.
empty: hide is part of the contract, not decoration. A card reporting "nothing
wrong" daily teaches people to stop reading the page, which is how a fleet log
reached 3,234 lines with 17 that mattered.
Frontend rendering comes next; the endpoint and declaration stand alone and
change nothing that exists.
The dashboard reports totals that are true every day and actionable on none of
them. Meanwhile a bay returned 500 to every collector report for a day and a
half, eleven markers' backups overwrote each other for weeks, and GE-Enforce
records failures, stale manifests and repeated self-heals that surface nowhere.
Every one of those was found by someone going to look.
Two things found while writing this shaped it. The plugin mechanism already
exists - get_dashboard_widgets, an endpoint that aggregates across enabled
plugins and isolates failures, and five plugins declaring widgets. And nothing
consumes it: the frontend never calls the endpoint and not one of the declared
components was ever written. So this finishes a half-built feature rather than
starting one.
It also proposes fixing the contract while it is still unused. Naming a
component per widget does not survive a lean build, where a plugin's component
may not be staged into the bundle at all. ADR-010 already solved this for asset
panels - declare data and a render mode, let a generic core component draw it -
and the same three renderers cover every card listed.
The rest is principles that came out of this week: empty cards shrink, because a
card that says "nothing wrong" daily trains people to stop reading, which is how
a log reached 3,234 lines with 17 that mattered; every row links to the thing;
cards declare a permission so the dashboard cannot become a way around RBAC;
thresholds are settings with neutral defaults.
Wave one is six cards whose data is already reliable. Wave two is the valuable
one: diffing what a manifest says a PC should have against what it reports
having, which nothing answers today and which is what GE-Enforce exists to
guarantee.
The kiosk take endpoint is the product's first unauthenticated
mutation; spell out the acceptance criteria (decrement-only, badge
attributed, bounded, physically rate-limited) so future open-write
endpoints meet the same bar. The dashboard-widget milestone is marked
optional: get_dashboard_widgets predates the ADR-010 data-only
renderers and needs a core component to render.
Design for a 3D-printed-parts storefront: item catalog with images and
quantity on hand, a transaction ledger attributing every take/restock/
adjust to a badge-scanned employee, an unauthenticated touch kiosk
(scan bin barcode, scan badge, keypad quantity), 1x0.5in CODE128 bin
labels, and stock/consumption/by-person reports.
The lab guide walks a developer through building it in seven
checkpointed milestones, reusing the USB badge contract, the
measuringtools migration baseline, the models-image upload trio, and
the open kiosk-endpoint precedents.
PCs now report enforcement results back to shopdb, closing the desired-vs-observed
loop.
- POST /api/geenforce/report (geenforce.report service token): each cycle a PC
posts the published version it applied, install/skip/fail/filtered counts, and
per-entry outcomes.
- Two tables: manifestenforcementreports (latest-per-host + history: applied
version, enforcer version, counts, derived status ok/selfhealed/failed) and
manifestenforcementresults (per entry: action installed/skipped/failed,
selfhealed flag, exit code, warning/error message).
- RECEIVED: reports carry the applied version; the admin view derives
receivedlatest by comparing it to the scope's current published version, so
the fleet view shows which PCs picked up an update.
- SELF-HEAL: per-entry action captures drift correction (installed when it
should already be present) vs skipped (already good) vs failed, with messages.
- Admin reads: GET /reports (fleet compliance rollup) and GET /reports/<id>
(per-entry detail). New geenforce.report permission.
- Tables added to the (undeployed) 0001 baseline; geenforce.post_report is a
service-token endpoint so it is exempt from the JWT authz sweep, like the
collector blueprint. 8 reporting tests; full suite green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Every publish is a permanent immutable revision (manifestpublishedversions),
kept indefinitely; optional retention policy (keep last M / prune older than N)
deferred, default keep-everything.
- Draft edits are not versioned (working copy overwrites), so field-level "who
changed what between publishes" rides the existing core audit system - no new
table, shows in the Audit Logs UI IT already uses.
- Runbook: History tab for published versions + roll back; Audit Logs for draft
edit provenance.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add an execution plan and simplify the design for average-site-IT operability
(the governing constraint from the review):
Model simplifications:
- One wide manifestentries table with an entrytype discriminator, not SQLAlchemy
STI subclasses and not a JSON blob. ~64 total entries fleet-wide make sparse
columns free and keep rows readable in plain SQL.
- Published snapshots freeze the rendered JSON document in a single manifestjson
column; drop the row-mirrored manifestpublishedentries family. Immutability is
structural, rollback is a one-flag flip, diff is a text diff.
- New manifestpayloads table for inline bytes with a ~1 MB app cap.
- regvalue stores the raw JSON literal (DWord typing); applymode/updatewindow
flagged inert-in-engine so the UI labels them.
Execution plan (section 13):
- Phases P0-P6 with gates; parity harness spec (two checks, IT-readable output,
~16-18 machine-profile fixtures); first vertical slice through
gea-shopfloor-cmm; ranked fail-fast risks.
- Milestone 1 = author + publish in shopdb, export to the share by a button,
engine/dispatcher/PCs unchanged. Real pain relief at zero client risk, with a
rollback IT already knows (restore the _meta/history backup).
- Export-to-share promoted to a first-class feature and permanent break-glass.
- Split permission geenforce.manage (edit) vs geenforce.publish (ship).
- Move Up/Down instead of drag-and-drop; a "what would this PC get" simulator
endpoint + UI; three-increment editor build.
- Two-source pctypemap transition window; scope-inventory reconciliation
(gea-shopfloor-display has no share dir).
- Plain-English IT day-to-day runbook proving the design is manageable.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Fold six review findings into docs/proposals/ge-enforce-plugin.md:
- Parity gate is behavioral equivalence, not byte-identity. Re-serialized JSON
differs in key order/whitespace/_comment formatting, so a raw diff never
converges; the test is same ordered entry set with identical detection/
targeting/action per entry.
- Dedicated payloadsha256 column, independent of detectionmethod. DetectionValue
is a SHA256 only for detectionmethod=Hash; MSIs with Registry/FileVersion
detection carry no payload hash, so an HTTP/inline fetch would otherwise run
unverified bytes. Client verifies fetched bytes against payloadsha256.
- Immutable published snapshots (manifestpublishedversions). Editing touches a
draft only; publish freezes a snapshot; the client is always served the latest
published snapshot, never the live draft; rollback republishes a prior
snapshot (the post-cutover safety net once the on-share JSON is retired).
- Scope uniqueness is (scopename, phase), not scopename alone; preinstall is one
flat scope gated internally by PCTypes, not per-pctype scopes.
- Alias graph: engine lib stays the single source of truth, shopdb only mirrors
it for validation; do not invert to engine-fetches-from-shopdb.
- Desired-vs-observed needs a new collector field (the installedVersions status
map), not existing data; flagged as a dependency.
Plus TLS trust for the SYSTEM-context client and importer skips .bak variants.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Metrology PCs (CMM, Keyence, Genspect, wax-and-trace imaging pc-types) drive
an attached measuring instrument. The PC itself stays a shopfloor PC, but the
collector now models the instrument:
- New METROLOGY_TOOL_MAP (pctypemap.py) maps those pc-types to a
MeasuringToolType (CMM, Vision System, Genspect, Form Tracer).
- ComputersPlugin._sync_measuringtool_link creates the MeasuringTool asset
once and a directional PC->tool "controls" relationship, tagged
collector:measuringtool. Idempotent (re-push reuses, no duplicate asset) and
self-archiving (a PC re-imaged to a non-metrology type deactivates the link
but keeps the asset and any calibration history). Mirrors the printer-link
pattern. The MeasuringToolType is created on demand if not seeded.
- 4 tests: create+link, idempotent re-push, non-metrology skip, repurpose
archives. Non-metrology PCs never warn about a missing controls type.
Settings rail cleanup:
- Collapsible groups so the 13-group rail fits without scrolling (1511px ->
488px). The group containing the current page expands; the rest collapse.
CSS-drawn caret (ASCII source, no Unicode). Empty groups never render, in
both the rail and the landing page.
- Measuring Tools group placed with the other asset groups (right after
Machines) instead of appended last; empty placeholder positions the
plugin-contributed cards.
- Operating Systems moved from PCs to General Reference: OS is cross-asset
(PCs, machines, measuring tools, network devices all run one).
Plus docs/proposals/ge-enforce-plugin.md: a planning doc for refactoring
GE-Enforce/DSC into a shopdb plugin (manifest as shopdb data, payloads on
SMB/HTTP/inline), grounded in the real manifest schema.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
