Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate › Plans › briefs › p6a-identity-tool-tree-instances-builder

P6a — identity verifier judges tool-tree template instances against their own root: builder brief (orchestrator's picks, 2026-10-07)

Source: plans/briefs/p6a-identity-tool-tree-instances-builder.md at 8a2cb42ad · last changed 2026-10-07 · first committed 2026-10-07 · 156 lines.

Prose pending.

Plan text

P6a — identity verifier judges tool-tree template instances against their own root: builder brief (orchestrator's picks, 2026-10-07)

Plan: plans/ast-daemon-deployment-plan.md § "P6a". Read it first; it holds the measured failure, the six executed rules and the acceptance. This brief holds the exact source at the sites, the changes per rule, the test plan and the gates. Design authority: ADR-0067 (Accepted) R1 "an enabled instance names data, not code" and P3 "the unit executes deployed code only"; the plan section records the rules as applications of those, not as new decisions.

1. Exact source at a3728f5a0

Read every symbol below with .venv/bin/python scripts/serialize_codebase_ast.py source <qname> --no-daemon (qualified names omit orchestrata_ultimate.; module residue with --residue).

[Service]
Type=simple
WorkingDirectory=/opt/orchestrata-tools
Environment=PYTHONUNBUFFERED=1
ExecStartPre=/usr/bin/test -e /%I/.git
ExecStart=/opt/orchestrata-tools/bin/ast-daemon --repo-root /%I --socket /%I/.claude/run/ast-daemon.sock
MemoryMax=3G
Restart=always
RestartSec=10

2. The changes (one per plan rule)

  1. Per-unit root (identity.py). Add a pure helper tool_tree_root(name: str, properties: Mapping[str, str]) -> Path | None in identity_scope.py: returns Path("/opt/orchestrata-tools") when the unit name has an instance ("@" in name.split(".service")[0] and the part after @ is non-empty) AND extract_argv0(properties["ExecStart"]) resolves under /opt/orchestrata-tools (string prefix after resolves_safely's leading-slash normalisation, no filesystem access); else None. Make the tools root a module constant TOOLS_ROOT = Path("/opt/orchestrata-tools") next to SYSTEM_PREFIXES and derive the prefix entry from it. In check_identity, per discovered unit, call it; when it returns a root, read that root's VERSION with parse_version (an unreadable or malformed tools VERSION is an errors entry naming the path, never a silent pass) and use (tools_root, tools_root / ".venv" / "bin" / "python", tools_version) in place of (root_resolved, venv_python, version) for check_c0 and _check_process_identity. Read the tools VERSION once per run, lazily.
  2. Instance parameter is data (identity_checks.py). check_c0 gains a keyword-only data_prefixes: Sequence[str] = (); a token equal to one of them or under one (same test resolves_safely applies to the root) is exempt. check_identity passes (instance_path,) for tool-tree instances, where instance_path is "/" + systemd_unescape(instance) computed in pure Python (implement systemd_unescape in identity_scope.py: - to /, \xHH to the byte; the live name decodes to /home/mohamed/workspace/orchestrata-ultimate-worktrees/wt-SPEC-110), with a unit test on that exact name. No systemd-escape subprocess.
  3. Report names the root. UnitFacts gains root: Path | None = None (default keeps every existing constructor call valid). IdentityReport.render() prints, for each unit with a root, one line judged <name> against <root> (ADR-0067 R1: instance parameter is data); as_dict() includes "judged_against" per unit. Existing output for other units is unchanged byte-for-byte (the CLI tests pin it).
  4. A tools deploy restarts live instances (deploy/install-tools.sh). Directly after VERSION is promoted (after line 629), for each template t in orchestrata-ast-daemon orchestrata-codemod-daemon: list active instances with systemctl --user list-units --plain --no-legend --all "$t@*.service" (the --plain rule from identity_scope.discover's docstring), and for every line whose ACTIVE column is active, systemctl --user restart <unit> and echo OK restarted <unit> (code under $PREFIX changed beneath it); a restart failure is fail "restart <unit>" (the deploy is then refused AFTER VERSION promotion — say so in the message: VERSION promoted; <unit> did not come back). Inactive/failed instances are not touched. Respect the script's existing SYSTEMCTL/dry-run seams if it has them; if it has none, read tests/deploy/test_install_tools.py to see how systemd is kept out of the test and follow it; if neither exists, STOP and report (do not invent a seam).
  5. Tests.
    • New tests/promotion/test_identity_tool_tree_instances.py, real transient units via _transient_unit with a tools-shaped root under tmp_path (VERSION in the commit/deployed format, .venv/bin/python as the python the transient unit runs; the existing test_full_happy_path_real_unit_real_proc shows the shape). Because the real tools root is the constant, add a seam: check_identity(..., tools_root: Path = TOOLS_ROOT) threaded to tool_tree_root; production passes nothing. Cases: (a) a template-named transient unit (name="orchestrata-ast-daemon@<escaped tmp repo>.service" — confirm systemd-run accepts a @ instance name; if it refuses, use the pattern seam plus a unit file written under an isolated --unit-dest-style directory as test_install_tools.py does, and say which in the report) whose argv0 is under the tools root, with --repo-root /<tmp repo> and a socket path under it: zero mismatches, report line names the tools root; (b) same unit plus a token under /home/<user>/workspace/…-shaped path outside both roots: one c0 mismatch naming it; (c) a template-named unit whose argv0 is under a checkout-shaped dir: judged against the product root, fails as today; (d) a plain unit: unchanged result and unchanged render; (e) start-time below the tools deployed: one start-time mismatch citing the tools timestamp; (f) systemd_unescape on the live name above and on - / \x2d mixes; (g) unreadable tools VERSION: an errors entry, exit code non-zero.
    • tests/deploy/test_install_tools.py: the restart block restarts only active instances of the two templates and nothing else, and a failed restart refuses with the message above.
    • tests/promotion/test_identity_cli.py and the other identity modules stay green and unchanged.
  6. Docs. docs/ship-and-deploy.md (the /opt/orchestrata-tools section) and deploy/systemd/README.md: one paragraph each — template instances are judged against the tools root, the instance parameter is data (R1), a tools deploy restarts active instances. @traces: the promotion package's existing decorators tell you which spec ids it cites; cite only ids that spec defines (check_spec_authority.py is the gate); if the package cites none, add none.

3. Gates and done-when