{
  "schema_version": "0.1",
  "artifact_type": "architecture",
  "canonical": true,
  "artifact_id": "ARCH-010",
  "agent_summary": {
    "title": "Portable repository module contract architecture",
    "status": "approved",
    "summary": "A source-pinned compiler produces one strict portable manifest; PRD Plugin validates and migrates it, AI-Collab admits and reconciles it, and every Hub consumes only current generation-matched effective state.",
    "last_reviewed_at": "2026-07-15",
    "load_notes": "Canonical JSON; the normative human contract and schema are under docs/specs/repository-module-contract-v1/."
  },
  "context": "PRD Plugin v0.16.2 already exposes repository identity, service declarations, tools, configuration, skills, workflows, knowledge, state, health, policy, and evidence through separate authorities. AI-Collab needs one normalized repository/module contract, while live admission and runtime state must remain outside repository truth.",
  "principles": [
    "One canonical manifest references existing authorities instead of duplicating them.",
    "Desired declarations and effective runtime state have different owners.",
    "UTCP is the tool-catalog authority; MCP is generated compatibility.",
    "Secrets are opaque late-bound requirements, never durable values.",
    "Stable identity plus generation guards prevents stale authorization.",
    "Compatibility is normalized once at the module boundary, not separately in nine Hubs.",
    "Unknown or unverifiable capability is denied rather than inferred."
  ],
  "components": [
    {"id": "ARCH-COMP-058", "summary": "Manifest schema and vocabulary", "responsibility": "Own the strict JSON Schema, stable identifiers, passive/routable mode, advertisements, governance, migration, provenance, and cross-domain glossary.", "requirement_ids": ["PRD-REQ-073", "PRD-REQ-074", "PRD-REQ-078", "PRD-REQ-080", "PRD-REQ-081"], "interface_ids": ["ARCH-IF-051", "ARCH-IF-052"]},
    {"id": "ARCH-COMP-059", "summary": "Repository authority compiler", "responsibility": "Read validated service, config, UTCP, skill, workflow, knowledge, state, health, and evidence authorities; emit one deterministic manifest plus field provenance and artifact digests.", "requirement_ids": ["PRD-REQ-073", "PRD-REQ-074", "PRD-REQ-075", "PRD-REQ-082"], "interface_ids": ["ARCH-IF-051", "ARCH-IF-053"]},
    {"id": "ARCH-COMP-060", "summary": "UTCP-first tool catalog normalizer", "responsibility": "Compile complete tool metadata from UTCP, preserve validated handler semantics, generate MCP compatibility, and expose transitional MCP-only gaps without making them authoritative.", "requirement_ids": ["PRD-REQ-076", "PRD-REQ-080", "PRD-NFR-040"], "interface_ids": ["ARCH-IF-054"]},
    {"id": "ARCH-COMP-061", "summary": "Portable governance compiler", "responsibility": "Validate roles, repo experts, specialist profiles, team templates, provider capability requirements, requested permissions, prompt-layer references, and workspace-policy precedence without creating live instances.", "requirement_ids": ["PRD-REQ-078", "PRD-REQ-079", "PRD-REQ-084"], "interface_ids": ["ARCH-IF-051", "ARCH-IF-055"]},
    {"id": "ARCH-COMP-062", "summary": "Compatibility and migration adapter", "responsibility": "Normalize legacy sources into the canonical contract with stable IDs, source authority, field provenance, conformance level, missing fields, parity evidence, migrations, and rollback.", "requirement_ids": ["PRD-REQ-082", "PRD-NFR-040", "PRD-NFR-041"], "interface_ids": ["ARCH-IF-053", "ARCH-IF-056"]},
    {"id": "ARCH-COMP-063", "summary": "Security and policy validator", "responsibility": "Reject resolved secret or credential fields, unsafe required fallbacks, undeclared authority, incompatible capabilities, and repository attempts to widen workspace policy.", "requirement_ids": ["PRD-REQ-077", "PRD-REQ-081", "PRD-REQ-084", "PRD-NFR-038", "PRD-NFR-039"], "interface_ids": ["ARCH-IF-052", "ARCH-IF-055"]},
    {"id": "ARCH-COMP-064", "summary": "Cross-domain admission contract", "responsibility": "Define the handoff to AI-Collab and shared stable-identity, desired-generation, revision-tuple, stale-observation, quarantine, health, and rollback invariants without owning module.binding storage.", "requirement_ids": ["PRD-REQ-075", "PRD-REQ-083", "PRD-REQ-084"], "interface_ids": ["ARCH-IF-052", "ARCH-IF-055", "ARCH-IF-056"]}
  ],
  "interfaces": [
    {"id": "ARCH-IF-051", "summary": "Repository authorities to compiler", "producer": "Validated PRD Plugin repository sources", "consumer": "Repository authority compiler"},
    {"id": "ARCH-IF-052", "summary": "Manifest submission envelope", "producer": "PRD Plugin compiler and validator", "consumer": "AI-Collab admission"},
    {"id": "ARCH-IF-053", "summary": "Legacy normalization envelope", "producer": "Compatibility adapter", "consumer": "Canonical manifest compiler"},
    {"id": "ARCH-IF-054", "summary": "Canonical tool catalog and generated projections", "producer": "UTCP tool catalog normalizer", "consumer": "Manifest offers and compatibility clients"},
    {"id": "ARCH-IF-055", "summary": "Desired governance and effective policy explanation", "producer": "Portable governance plus workspace policy", "consumer": "AI-Collab Permissions and Agents & Teams Hubs"},
    {"id": "ARCH-IF-056", "summary": "Cross-spec conformance fixtures", "producer": "PRD Plugin contract package", "consumer": "PRD Plugin compiler, AI-Collab admission/binding, and legacy adapters"}
  ],
  "decisions": [
    {"id": "ARCH-DEC-047", "summary": "Use one canonical manifest with referenced sub-schemas and source authorities.", "rationale": "Multiple independent manifests would drift and force AI-Collab to scrape plugin internals.", "source_ids": ["PRD-REQ-073", "PRD-REQ-074"]},
    {"id": "ARCH-DEC-048", "summary": "Keep desired declarations in PRD Plugin and live admission/effective state in AI-Collab.", "rationale": "Separating portable intent from environment-specific authority prevents dual ownership and stale repository runtime state.", "source_ids": ["PRD-REQ-075", "PRD-REQ-083"]},
    {"id": "ARCH-DEC-049", "summary": "Make UTCP the canonical tool catalog and MCP a generated compatibility view.", "rationale": "One catalog prevents schema, permission, and side-effect drift across transports.", "source_ids": ["PRD-REQ-076"]},
    {"id": "ARCH-DEC-050", "summary": "Use typed opaque secret references with late runner-bound resolution.", "rationale": "Durable, replay, vector, log, and wiki surfaces must never become secret stores.", "source_ids": ["PRD-REQ-077", "PRD-NFR-038"]},
    {"id": "ARCH-DEC-051", "summary": "Require repo_expert only for agent-routable modules.", "rationale": "Passive knowledge/tool modules remain lightweight while routable modules have an explicit expert contract.", "source_ids": ["PRD-REQ-078"]},
    {"id": "ARCH-DEC-052", "summary": "Use stable logical binding identity plus monotonic desired generation and exact revision tuple matching.", "rationale": "Manifest-version identity creates competing bindings; generation matching prevents late observations from resurrecting superseded authority.", "source_ids": ["PRD-REQ-083"]},
    {"id": "ARCH-DEC-053", "summary": "Normalize legacy compatibility once at the module boundary.", "rationale": "Nine Hub-specific adapters would create nine migrations and permanent divergence.", "source_ids": ["PRD-REQ-082"]},
    {"id": "ARCH-DEC-054", "summary": "Defer Fork changes until conformance or contention tests prove a missing generic primitive.", "rationale": "Existing identity, transaction, event, provenance, subscription, and retrieval primitives appear sufficient for v1.", "source_ids": ["PRD-REQ-083", "PRD-NFR-040"]}
  ],
  "risks": [
    {"id": "ARCH-RISK-042", "summary": "The compiler duplicates source data and becomes a competing authority.", "mitigation": "Store references, status, provenance, and digests; validate freshness and regenerate rather than hand-edit derived fields.", "status": "open"},
    {"id": "ARCH-RISK-043", "summary": "A manifest declaration is treated as an effective permission grant.", "mitigation": "Label it admission input, default-deny, compute effective policy in AI-Collab, and recheck at every execution/mutation boundary.", "status": "open"},
    {"id": "ARCH-RISK-044", "summary": "Resolved secrets or provider diagnostics leak through manifests, health, logs, replay, or indexes.", "mitigation": "Strict schemas, recursive forbidden-field tests, opaque handles, permission-filtered readiness, and sanitized diagnostics.", "status": "open"},
    {"id": "ARCH-RISK-045", "summary": "The richer native MCP surface remains a second catalog during UTCP migration.", "mitigation": "Mark MCP-only gaps, generate compatibility from UTCP, require parity fixtures, and deprecate the native catalog only after guarded write-path parity.", "status": "open"},
    {"id": "ARCH-RISK-046", "summary": "A stale reconciliation or health response reauthorizes a superseded capability.", "mitigation": "Project only on exact generation/digest/revision/policy match and discard late observations.", "status": "open"},
    {"id": "ARCH-RISK-047", "summary": "Legacy adapters silently invent missing capability or weaken policy for parity.", "mitigation": "Classify fields as native, derived, missing, or legacy_adapter; quarantine unknowns; require equal or stricter permission parity and rollback evidence.", "status": "open"}
  ],
  "validation_strategy": [
    "RED/GREEN conformance tests for package existence, source pins, passive/routable conditional rules, UTCP authority, and secret exclusion.",
    "Draft 2020-12 validation of all positive and negative fixtures.",
    "Compiler determinism and digest tests against repository-owned authorities at a pinned revision.",
    "Cross-spec fixtures for admission, nine-Hub projection, effective permissions, stale generation withdrawal, provider readiness redaction, and rollback.",
    "Legacy/native parity fixtures proving stable IDs, preserved state/config, equal or stricter permissions, and one normalized Hub representation.",
    "Independent code review plus focused and repository-wide gates before any implementation or release claim."
  ],
  "traceability": {
    "source_ids": ["PRD-010", "PRD-REQ-073", "PRD-REQ-074", "PRD-REQ-075", "PRD-REQ-076", "PRD-REQ-077", "PRD-REQ-078", "PRD-REQ-079", "PRD-REQ-080", "PRD-REQ-081", "PRD-REQ-082", "PRD-REQ-083", "PRD-REQ-084"],
    "decision_ids": [],
    "implementation_task_ids": ["IMP-TASK-089", "IMP-TASK-090", "IMP-TASK-091", "IMP-TASK-092", "IMP-TASK-093", "IMP-TASK-094", "IMP-TASK-095", "IMP-TASK-096"],
    "tracking_ids": [],
    "health_ids": []
  }
}