feat(modules/synapse): upgrade manifest to v2 cataloging #104

New issue

Closed

opened 2026-05-06 00:26:06 +02:00 by claude · 0 comments

claude commented

2026-05-06 00:26:06 +02:00

Collaborator

Decomposed from meta-issue #70 — Phase 02 v2 cataloging pilot. Priority rank: 8/8.

Spec sources (whitelist)

modules/synapse/module.yaml — current v1 manifest
modules/synapse/runbook.md — operator runbook (if exists)
schema/module.schema.v2.json — v2 fields spec
schema/module.schema.json — v1 baseline
Live runtime via SSH: docker inspect <container-from-runbook> on appropriate host (RS 2000 unless module is VPS-1000)
AGENTS.md §"Current phase" — v2 audit fields list

Extracted context

From schema/module.schema.v2.json description:

Additive extension to v1. Backwards-compatible: v1 manifests pass v2 with warnings only on missing v2-specific fields.
v2 fields: predecessor, alternatives, todo_cap, drift_audit.

From AGENTS.md §"Current phase":

spec.intent.purpose, spec.intent.user_facing_outcome, spec.intent.acceptance_criteria,
spec.runtime.image_observed (full digest, no truncation),
spec.runtime.statefulness, optional spec.risk.acknowledged_risks

Why this exists (product-first)

Synapse is operator's primary chat (Matrix homeserver). Stateful — chat history persists. v2 cataloging surfaces statefulness for cutover planning + Issue #45 restore-test scope decisions.

Allowed touched paths

modules/synapse/module.yaml (modify) — ONLY

Do NOT touch other manifests, schema files, runbook (separate atomic if runbook needs update), or any code.

What "done" looks like

spec.intent.purpose written (1 line)
spec.intent.user_facing_outcome written (≤4 sentences; user/owner-facing language, not tech)
spec.intent.acceptance_criteria written (≥2 verifiable bullets)
spec.runtime.image_observed matches live docker inspect <container> RepoDigests output (FULL sha256:... digest, no truncation)
spec.runtime.image_audit_ts set to RFC3339 UTC of when verified
spec.runtime.image_build set to 'registry' or 'local'
spec.runtime.statefulness set to 'stateful'
spec.risk.acknowledged_risks documents Matrix-state-loss-on-restore + bridge-data implications
module.yaml validates against module.schema.v2.json (manual: python3 -m jsonschema -i modules/synapse/module.yaml schema/module.schema.v2.json; auto via platformctl validate once #63 lands)

Suggested approach

Read current modules/synapse/module.yaml to know baseline
SSH to host, run docker inspect for the running container, capture RepoDigest
Read runbook (if exists) for user-facing context
Fill v2 fields per "What done looks like" checklist
Validate locally via jsonschema before opening PR
Run tests/smoke.sh synapse — should still pass (this PR shouldn't change runtime behavior)

Escape hatch

If image_observed from runtime differs from current manifest: STOP, comment on this issue with the discrepancy. Do NOT silently fix manifest — that's a separate decision (manifest correction vs runtime drift).
If runbook claims behavior the module doesn't actually do: STOP, comment.
If module is on a different host than runbook claims: STOP, comment.

Risk class

risk/process — incorrect v2 manifest blocks platformctl validate; downstream blocks Phase 03

Dependencies

Depends on Issue #63 (platformctl validate jsonschema) — until #63 lands, agent uses python3 -m jsonschema directly
Depends on Issue #66 (L4-Verify suite) — once #66 lands, this PR auto-validated end-to-end

Trace

Parent meta-issue: #70
Priority rank: 8/8 per #70 heuristic
Decomposed by: claude (orchestrator), 2026-05-06
Per agent-execution-template.md: spec sources whitelist + extracted context + allowed touched paths + escape hatch

**Decomposed from meta-issue #70 — Phase 02 v2 cataloging pilot. Priority rank: 8/8.** ## Spec sources (whitelist) - `modules/synapse/module.yaml` — current v1 manifest - `modules/synapse/runbook.md` — operator runbook (if exists) - `schema/module.schema.v2.json` — v2 fields spec - `schema/module.schema.json` — v1 baseline - Live runtime via SSH: `docker inspect <container-from-runbook>` on appropriate host (RS 2000 unless module is VPS-1000) - `AGENTS.md` §"Current phase" — v2 audit fields list ## Extracted context > From `schema/module.schema.v2.json` description: > ``` > Additive extension to v1. Backwards-compatible: v1 manifests pass v2 with warnings only on missing v2-specific fields. > v2 fields: predecessor, alternatives, todo_cap, drift_audit. > ``` > From `AGENTS.md` §"Current phase": > ``` > spec.intent.purpose, spec.intent.user_facing_outcome, spec.intent.acceptance_criteria, > spec.runtime.image_observed (full digest, no truncation), > spec.runtime.statefulness, optional spec.risk.acknowledged_risks > ``` ## Why this exists (product-first) Synapse is operator's primary chat (Matrix homeserver). Stateful — chat history persists. v2 cataloging surfaces statefulness for cutover planning + Issue #45 restore-test scope decisions. ## Allowed touched paths - `modules/synapse/module.yaml` (modify) — ONLY Do NOT touch other manifests, schema files, runbook (separate atomic if runbook needs update), or any code. ## What "done" looks like - [ ] `spec.intent.purpose` written (1 line) - [ ] `spec.intent.user_facing_outcome` written (≤4 sentences; user/owner-facing language, not tech) - [ ] `spec.intent.acceptance_criteria` written (≥2 verifiable bullets) - [ ] `spec.runtime.image_observed` matches live `docker inspect <container>` RepoDigests output (FULL `sha256:...` digest, no truncation) - [ ] `spec.runtime.image_audit_ts` set to RFC3339 UTC of when verified - [ ] `spec.runtime.image_build` set to 'registry' or 'local' - [ ] `spec.runtime.statefulness` set to 'stateful' - [ ] `spec.risk.acknowledged_risks` documents Matrix-state-loss-on-restore + bridge-data implications - [ ] `module.yaml` validates against `module.schema.v2.json` (manual: `python3 -m jsonschema -i modules/synapse/module.yaml schema/module.schema.v2.json`; auto via `platformctl validate` once #63 lands) ## Suggested approach 1. Read current `modules/synapse/module.yaml` to know baseline 2. SSH to host, run `docker inspect` for the running container, capture RepoDigest 3. Read runbook (if exists) for user-facing context 4. Fill v2 fields per "What done looks like" checklist 5. Validate locally via jsonschema before opening PR 6. Run `tests/smoke.sh synapse` — should still pass (this PR shouldn't change runtime behavior) ## Escape hatch - If `image_observed` from runtime differs from current manifest: STOP, comment on this issue with the discrepancy. Do NOT silently fix manifest — that's a separate decision (manifest correction vs runtime drift). - If runbook claims behavior the module doesn't actually do: STOP, comment. - If module is on a different host than runbook claims: STOP, comment. ## Risk class - [x] `risk/process` — incorrect v2 manifest blocks platformctl validate; downstream blocks Phase 03 ## Dependencies - **Depends on Issue #63** (platformctl validate jsonschema) — until #63 lands, agent uses `python3 -m jsonschema` directly - **Depends on Issue #66** (L4-Verify suite) — once #66 lands, this PR auto-validated end-to-end ## Trace - Parent meta-issue: #70 - Priority rank: 8/8 per #70 heuristic - Decomposed by: claude (orchestrator), 2026-05-06 - Per agent-execution-template.md: spec sources whitelist + extracted context + allowed touched paths + escape hatch

claude added the

phase/02

proposed

labels

2026-05-06 00:26:45 +02:00

claude referenced this issue

2026-05-06 00:27:25 +02:00

[meta] Phase 02 v2 cataloging — first 5-10 priority modules to v2 #70