f9d6b57f0f
The docs lived on one lineage and the fleet code on another. That is why six pages described a shared fleet key as how an agent authenticates, why COLLECTOR-AUTH had to warn that the per-PC credential code was not in the repository it sat in, and why ADR-019 recorded a decision whose implementation was somewhere else. Documentation that cannot see the code it documents goes stale by construction, and no amount of editing fixes that. So the corpus moves here: 84 files, 56 pages, 20 ADRs, the proposals, INDEX.md, llms.txt and both gates. Filenames are unchanged, because a wiki page name is derived from the filename and a rename breaks every link anybody saved. THE POINT OF THE MOVE IS THE CORRECTION IT ENABLES. Every caveat that said "not in this tree" was false the moment the files landed beside the code, so each was rewritten from what is actually here: - COLLECTOR-AUTH gained the real enroll request body, the two bounds on the unauthenticated route (per-IP rate limit, pending cap with stale rows dropped before a real PC is refused), and the rejected pending reason that binds to the endpoint identity rather than the nonce. - ADR-019 now describes an implementation that is present, including its tests, and says plainly that what remains is the FLEET migration, not the code. - proposals/device-identity claimed phase 1 was unbuilt. plugins/computers declares deviceid on the collector schema and prefers it over the older fallbacks. Corrected in the page, its summary and the index. WINDOWS/IIS IS NOW DOCUMENTED AS THE LEGACY PATH, per the product decision, and carefully: it is what production runs today. Every Windows page opens by saying it is supported, not for a new site, and where a new site should go instead. No procedure was cut - an operator on an IIS box at 2am needs these pages to work exactly as well tomorrow. MIGRATE-TOPOLOGY stops being a footnote and becomes the off-ramp, which is why it nearly doubled: what was there did not match how the Docker stack really works here. The Docker material that already lived on this line was kept and given ownership rather than buried under the ported Windows-centric prose: DEPLOY now describes the four services, the migrate service that runs the upgrade chain before api starts, TLS terminated by nginx, and the plugin count corrected from thirteen to seventeen - a number both lineages had wrong. ROADMAP is rewritten from evidence rather than memory: what has shipped, read out of the changelog, the ADRs and the manifests, and ahead of it exactly two items - finalize a distributed release and polish the setup wizard. PROJECT-MAP is generated and was stale; the GENERATOR was what was wrong. --check passes now. API-REFERENCE is retired to a pointer. /api/docs serves 573 operations with derived auth, query parameters and harvested examples, and a hand-written page competing with that is a liability. The file stays so its wiki page and its inbound links survive. AND THE MOVE TURNED ON A SCRUB THAT HAD NEVER RUN HERE. test_docs_publishable keys on docs/*.md, which this line did not have, so it skipped - its own comment predicted what would surface. Porting the corpus activated it and it found 48 lines that must not reach a published wiki: branch names abbreviating the site, assistant-tooling paths, the site name in two deployment pages, and an employee ID in a Windows path that the scrub does not even look for.
236 lines
11 KiB
Markdown
236 lines
11 KiB
Markdown
<!-- docmeta
|
|
purpose: explanation
|
|
audience: developer
|
|
status: historical
|
|
summary: Plan for one durable identity for the device a PC drives. Phase 1 is built here; phases 2 and 3 are not started.
|
|
loadwith: none
|
|
-->
|
|
|
|
# Proposal: one identity for the device a PC drives, ending in the registry
|
|
|
|
Status: PHASE 1 BUILT AND IN THIS TREE - `plugins/computers/plugin.py` declares
|
|
`deviceid` on the computers collector schema and prefers it over the older
|
|
per-family fallbacks. Phases 2 and 3 not started.
|
|
Author: planning session 2026-08-20.
|
|
|
|
## 1. What this is
|
|
|
|
A shop-floor PC often drives something: a CMM, a Keyence, a Genspect, a
|
|
wax-trace unit, a part marker. ShopDB needs to know WHICH one, and the answer
|
|
has to survive the PC being replaced.
|
|
|
|
Today that answer is assembled from whatever each bay family happens to have,
|
|
and two of the three sources are derived from the PC itself, so they do not
|
|
survive a swap. This proposal converges them on one identity, moves it from
|
|
files to the registry, and does it in three phases so no bay is stranded.
|
|
|
|
## 2. Why PC-derived identity fails
|
|
|
|
Two mechanisms stand in for a real identity today:
|
|
|
|
- **Reuse**: look for a prior collector link from THIS PC asset.
|
|
- **Mint**: build `<PC assetnumber>-<SUFFIX>`, and a PC's asset number is its
|
|
hostname.
|
|
|
|
Both survive a re-image. Neither survives a PC SWAP. A new hostname is a new PC
|
|
asset with no prior link and a predicted number that has never existed, so the
|
|
same physical device gets a SECOND record while the first keeps its config and
|
|
its backup history under a dead PC's name.
|
|
|
|
That is not hypothetical: minting from the hostname left 43 legacy `MT-####`
|
|
tools shadowed by minted twins, three records deep in places.
|
|
|
|
## 3. The rail that must not be crossed
|
|
|
|
`machinenumber` answers "WHICH BAY is this" and is what GE-Enforce
|
|
`TargetMachineNumbers` gates on. The device identity answers "WHICH DEVICE is
|
|
this". They are different facts and must stay in different fields.
|
|
|
|
Putting a device id into the machine-number channel would silently stop every
|
|
bay-gated manifest entry from matching - a failure that looks like nothing
|
|
happening, on every cycle, with no error anywhere.
|
|
|
|
## 4. Where identity comes from today
|
|
|
|
| Bay family | Identity source | Survives a PC swap |
|
|
|---|---|---|
|
|
| DNC / collections | `MachineNo` in the eDNC/NTLARS registry | yes |
|
|
| CMM | `C:\Enrollment\cmm\cmmid.txt` | yes, but see below |
|
|
| Keyence, Genspect, wax-trace | nothing, before phase 1 | no |
|
|
| Part markers | nothing, before phase 1 | no |
|
|
|
|
**`cmmid.txt` is not only an identity file.** It is a PATH KEY, and that is why
|
|
it cannot simply be retired:
|
|
|
|
| Consumer | Use |
|
|
|---|---|
|
|
| `resolve-cmm-bay-config.ps1` | writes it |
|
|
| `Verify-And-Heal-Staging.ps1` | stages `installers-post\cmm\backups\<cmmid>` |
|
|
| `09-Setup-CMM.ps1` | locates the bay's staged backup set |
|
|
| `Restore-CMM.ps1` | restores from `<BackupRoot>\<cmmid>\`, same-bay by design |
|
|
| collector | reads it as `machineNo` |
|
|
|
|
Only the last row is an identity use. The rest address directories by it.
|
|
|
|
It is also doing the job badly: for a CMM bay it reports the INSTRUMENT's id in
|
|
the `machinenumber` channel, and the server then resolves it back to a measuring
|
|
tool at step 4 of its own fallback chain. That round trip is what phases 2 and 3
|
|
remove.
|
|
|
|
## Phase 1 - one field, one file (DONE)
|
|
|
|
The collector accepts a single `deviceid`, read from `C:\Enrollment\asset-id.txt`
|
|
and resolved BEFORE anything PC-derived, for every device family.
|
|
|
|
- One file for every bay with no `MachineNo` registry to identify it.
|
|
- It names the asset and NOT its type: the pc-type already says what kind of
|
|
device it is, through `SUBORDINATE_DEVICE_MAP`, so a device type declared
|
|
later through `subordinatedevice_<pctype>` needs no new file and no client
|
|
change.
|
|
- Wire field is `deviceid`, not `assetid`, because `assetid` is already this
|
|
contract's RESPONSE field for a PC's integer primary key.
|
|
- `measuringtoolid` (0.12.0) is accepted as an alias and the older file is still
|
|
read, so a bay staged in that window keeps reporting.
|
|
- Guards: an unresolvable value warns rather than minting a phantom, and a value
|
|
resolving to the WRONG KIND of asset is refused with the asset named.
|
|
|
|
Nothing was removed. Every previous fallback still runs, one place lower.
|
|
|
|
## Phase 2 - imaging writes it, and `cmmid.txt` stops being an identity
|
|
|
|
Repository: the PXE/imaging repo, not this one. **Needs deploying to the live
|
|
server, not only committing** - the live boot image is authoritative.
|
|
|
|
1. `resolve-cmm-bay-config.ps1` writes `C:\Enrollment\asset-id.txt` ALONGSIDE
|
|
`cmmid.txt`. Two files, two questions: the identity, and the backup-set key.
|
|
`cmmid.txt` keeps every path use it has today.
|
|
2. Every other device pc-type writes `asset-id.txt` at imaging from its bay
|
|
config. Bays with no device write nothing, and the file's absence stays
|
|
meaningful.
|
|
3. The collector demotes `cmmid.txt` to last place in the machine-number chain
|
|
and stops being the intended path for CMM identity. It is still read, so a
|
|
grandfathered bay that never gets re-imaged keeps reporting.
|
|
4. The value written is the device's `assetnumber` as ShopDB holds it. Where a
|
|
CMM's asset number is already its bay id (`CMM3`), phase 2 is a no-op in
|
|
content and a change only in which file carries it.
|
|
|
|
Exit criterion: a report from a re-imaged bay of each device family carries
|
|
`deviceid`, and no bay of those families relies on the `cmmid.txt` fallback.
|
|
The collector response warnings are the check: an adopted device is silent, a
|
|
minted one is not.
|
|
|
|
## Phase 3 - identity moves to the registry
|
|
|
|
`HKLM:\SOFTWARE\GE\ShopDB\DeviceId`.
|
|
|
|
This is the destination because the registry survives the profile cleanup and
|
|
disk hygiene that eats `C:\Enrollment`, is readable as SYSTEM with no file ACL
|
|
to get wrong, and is already how a DNC bay is identified. It needs no new key
|
|
and no new read path: the collector already opens
|
|
`HKLM:\SOFTWARE\GE\ShopDB` (and the `WOW6432Node` variant) for `BaseUrl` and
|
|
`ApiToken`, and `Install-GEEnforce.ps1` already writes that key.
|
|
|
|
**One value, every family.** `DeviceId` is a single registry value, not a key
|
|
per device type. The client sends one field and the pc-type decides which sync
|
|
consumes it, exactly as `asset-id.txt` works in phase 1, so:
|
|
|
|
| Bay | `DeviceId` holds | Replaces |
|
|
|---|---|---|
|
|
| CMM | the instrument's `assetnumber` | `cmmid.txt` as IDENTITY only |
|
|
| Keyence | the instrument's `assetnumber` | nothing; had none |
|
|
| Genspect | the instrument's `assetnumber` | nothing; had none |
|
|
| wax-trace | the instrument's `assetnumber` | nothing; had none |
|
|
| part marker | the marker's `assetnumber` | minting from the hostname |
|
|
|
|
A device family added later through `subordinatedevice_<pctype>` is covered on
|
|
the day it is declared, with no client change and no new registry value.
|
|
|
|
Resolution order after phase 3:
|
|
|
|
1. `HKLM:\SOFTWARE\GE\ShopDB\DeviceId`
|
|
2. `C:\Enrollment\asset-id.txt`
|
|
3. `C:\Enrollment\measuringtool-id.txt` (0.12.0 window)
|
|
4. `C:\Enrollment\cmm\cmmid.txt` as `machineNo` (grandfathered CMM bays)
|
|
|
|
Then, and only then, the file branches can be deleted one at a time, newest
|
|
first, each when no bay has reported through it for a full inventory cycle.
|
|
|
|
**`cmmid.txt` survives phase 3 regardless**, as the CMM backup-set path key. It
|
|
is not on the deletion list; only its identity use is.
|
|
|
|
### PXE and GE-Enforce prefer it too, not just the collector
|
|
|
|
Phase 3 is not only "the collector reads a registry value". All three writers
|
|
and readers move together:
|
|
|
|
| Component | Change |
|
|
|---|---|
|
|
| PXE / imaging | writes `DeviceId` at enrollment instead of (or as well as) the file |
|
|
| GE-Enforce | resolves device identity registry-first, mirroring how it already resolves the machine number |
|
|
| collector | reads the registry ahead of the file |
|
|
|
|
**GE-Enforce already made this exact decision for the machine number, and wrote
|
|
down why.** `Install-FromManifest.ps1` resolves `TargetMachineNumbers` gating
|
|
from the eDNC registry BEFORE `C:\Enrollment\machine-number.txt`, because:
|
|
|
|
> the imaging-time `machine-number.txt` is written ONCE by `startnet.cmd` at the
|
|
> PXE menu and is NOT updated on reassignment, so it goes stale.
|
|
|
|
**`asset-id.txt` inherits that defect exactly.** It is written once at imaging
|
|
and nothing updates it when a device is swapped, moved between bays, or
|
|
replaced. The bay then reports an identity that was true on imaging day, and the
|
|
collector - which now trusts that value FIRST, ahead of every other source -
|
|
adopts the wrong device with no warning, because the value still resolves.
|
|
|
|
That makes phase 3 a correctness fix rather than a tidy-up. A file that only
|
|
imaging writes cannot be the top of a resolution order for something that
|
|
changes during a PC's life.
|
|
|
|
It also implies a reassignment path, the way `Set-MachineNumber` /
|
|
`Update-MachineNumber` exist for the bay number: something that rewrites
|
|
`DeviceId` when a device is swapped, and migrates any per-device state with it.
|
|
Without that, phase 3 moves the staleness from a file to a registry value rather
|
|
than curing it.
|
|
|
|
### Doing phase 3 early is cheaper than doing it late
|
|
|
|
If the registry read lands before imaging is changed, phase 2 can write the
|
|
REGISTRY for new bays and skip the file era entirely for them. The file then
|
|
exists only for bays staged in the window between phase 1 and phase 2, and the
|
|
eventual cleanup is deleting a code branch rather than sweeping the fleet.
|
|
|
|
The cost of adding the read now is one branch in the client and one row in the
|
|
docs. The cost of adding it after every bay has a file is a migration.
|
|
|
|
## 5. What this does not change
|
|
|
|
- `machinenumber` and its GE-Enforce gating. Untouched in all three phases.
|
|
- A part marker still files `partof` the operation from `machinenumber`. The
|
|
device identity says WHICH marker the PC controls, not which operation that
|
|
marker belongs to.
|
|
- Minting. It stays as the last resort for a bay that names nothing, because a
|
|
device nobody declared is still better recorded than not recorded. Anything
|
|
minted should be treated as a placeholder to be reconciled.
|
|
|
|
## 6. Before phase 2: find what is already duplicated
|
|
|
|
Phase 1 stops NEW duplicates. It does not merge the ones a PC swap has already
|
|
created. Before imaging starts writing files, run a read-only query for device
|
|
assets whose controlling PC no longer exists, or whose asset number carries a
|
|
hostname that is not a current PC. That list is the reconciliation backlog, and
|
|
it is much easier to read before the fleet starts reporting new identities over
|
|
the top of it.
|
|
|
|
## 7. Rollback
|
|
|
|
Each phase is independently reversible because nothing is removed until the
|
|
phase after it proves the replacement:
|
|
|
|
- Phase 1: stop sending `deviceid` and every previous fallback still runs.
|
|
- Phase 2: stop writing `asset-id.txt` and bays fall back to what they used
|
|
before.
|
|
- Phase 3: stop writing the registry value and bays fall back to the file.
|
|
|
|
The only irreversible step is deleting a fallback branch, which is deliberately
|
|
outside all three phases.
|