# PRD Plugin Repository Module Contract v1 Status: approved implementation contract Owner: PRD Plugin Source cutoff: PRD Plugin `v0.16.2` at `ff1fb2ff7ef8e48ef48d7aec9b090e8ebddf6944` Requirements artifact: `PRD-010` Approved baseline: `MSG-mrmmvp3c-xcrxm6` and `SP-mrmmvg11-vkf9fe` ## Purpose This contract defines the portable desired state that a PRD-enabled repository submits to AI-Collab for admission. It replaces discovery by scraping unrelated PRD Plugin internals with one versioned `module.manifest` envelope whose fields remain traceable to their source authorities. The normative package is: - `module-manifest.schema.json` — the PRD Plugin-owned JSON Schema; - this document — terminology, ownership, invariants, and lifecycle rules; - `fixtures/` — cross-domain conformance examples shared with AI-Collab. The schema is normative for document shape. This document is normative for ownership, policy precedence, security, lifecycle, and failure behavior. The fixtures are normative compatibility cases; an implementation must not weaken a fixture merely to accept a legacy declaration. ## Current truth and target truth The source cutoff already ships repository identity, typed service `consumes`/`provides`, configuration inventory, validated MCP operations, a read-only UTCP surface, skills, workflows, scripts, wiki/state knowledge, privacy policy, health, evidence, and deterministic workflow receipts. These authorities are fragmented across `.prd_plugin/services.json`, configuration, tool manuals, state, install manifests, and method artifacts. This contract is the approved target compilation boundary. It does not claim that the v1 manifest compiler, complete UTCP catalog, AI-Collab admission path, or native module migrations are already shipped. Historical sources must be classified as `shipped`, `proposed`, `deferred`, `superseded`, or `dirty_candidate`; unclassified material is not implementation truth. ## Ownership seam PRD Plugin owns: - the portable manifest schema and terminology; - compilation from repository-owned source authorities; - templates, migrations, validation, provenance, and conformance evidence; - desired roles, agent profiles, team templates, provider requirements, permission requests, and secret requirements; - compatibility adapters that normalize legacy repository declarations. AI-Collab owns admission and all effective runtime state: - repository discovery and the materialized module registry; - compatibility resolution, effective permissions, approval state, provider resolution, and secret readiness; - stable logical bindings, desired generations, observed reconciliation, live health, runners, routes, participant/session instances, and current roster; - projection into the nine Hubs: Repos & Modules, Tools, Knowledge, Configuration, Skills, Permissions, Agents & Teams, Observability, and Apps. Fork remains the generic substrate for durable identity, capability/resource records, transactions, events, subscriptions, provenance, causal history, and retrieval. A new Fork primitive is deferred until conformance or contention tests prove the generation guard cannot be expressed safely above it. The manifest is a declaration submitted for admission, never trusted runtime authority. A repository can request a capability, permission, provider class, or autonomy default; it cannot grant itself one or override workspace policy or the consent floor. ## Contract model ### Identity and mode `module_id` is stable across versions and migrations. `module_mode` is one of: - `passive` — knowledge, tools, configuration, schemas, or other contributions without agent routing. A `repo_expert` profile is optional. - `agent_routable` — the module may receive routed agent work. At least one agent profile with `profile_kind: repo_expert` is required. Changing a manifest version does not create a new logical runtime binding. ### Advertisements - `consumes` names versioned service or capability contracts the module calls. - `needs` describes admission preconditions: permissions, approvals, typed opaque secret references, host/runtime features, models, ports, and compatibility constraints. Each need declares required/optional behavior and explicit block/degrade fallback. - `offers` describes contributions: tools, knowledge, configuration schemas, skills, workflows, data contracts, app contributions, runners, observability, and agent profile references. An offer describes discoverable capability; it does not authorize discovery, read, invocation, dispatch, mutation, or mounting. AI-Collab computes those effective rights and every execution boundary rechecks them. ### Tools UTCP is the canonical tool catalog. Every tool declaration carries its UTCP manual reference, schemas, side-effect class, idempotency, permissions, approval policy, timeout, and health metadata. MCP is a generated compatibility projection. During migration, native MCP-only operations are reported as a conformance gap; they do not establish a second source of truth. Validated handlers retain locking, consent, authorization, input validation, and audit enforcement regardless of transport. ### Agents, teams, and providers Portable desired state keeps four concepts separate: - roles — reusable responsibilities, capabilities, skills, data boundaries, permissions, and escalation rules; - agent profiles — repository-specific instructions, role references, tool and knowledge scope, supported task types, handoffs, and model capabilities; - team templates — desired composition, routing topology, concurrency, required/optional seats, handoffs, and separation-of-duty rules; - provider policy — allowed provider classes, model capability requirements, privacy/residency constraints, fallback preferences, and budget class. Concrete provider accounts, endpoints containing credentials, quota balances, live participant or session IDs, availability, health, and active assignments belong only to AI-Collab's binding and roster. ### Secrets Resolved secret values and provider credentials are forbidden in the manifest, Fork records, causal history, replay payloads, logs, embeddings, wiki, and indexes. The manifest may contain only typed opaque secret requirements or references: identifier, purpose, scope, provider class, required/optional behavior, and rotation policy. AI-Collab resolves a reference only after admission and injects a provider- scoped handle at the runner boundary. Secret readiness is permission-filtered and exposes only the minimum state needed, such as `ready`, `missing`, `denied`, or `invalid`; provider diagnostics require an authorized admin/debug scope. ### App and runner declarations An app contribution declares route namespace, navigation placement, mount point, host API range, asset references, permissions, and isolation. AI-Collab retains global shell ownership. A runner declares command or handler reference, health endpoint, log reference policy, startup dependencies, rollback contract, and secret-reference IDs; it never embeds a resolved secret. ## Runtime binding invariants The binding schema is owned by AI-Collab, but both specifications must enforce these shared invariants: 1. Logical identity is stable as `workspace_id + repo_id + module_id + environment`. 2. Every desired mutation increments a monotonic generation and records the manifest version, digest, implementation revision, and admission-policy version. 3. Observed state records `reconciled_generation` plus the exact digest, implementation revision, and policy version it evaluated. 4. A capability projects only when desired and observed generations and the complete revision tuple match. 5. The hard invariant is: stale observed state never authorizes. Late health or reconciliation results from an older generation cannot resurrect a superseded capability. 6. Unknown, incompatible, denied, or unverifiable capabilities are quarantined and default-denied, not partially granted. ## Policy precedence Effective policy is the most restrictive result of the workspace emergency controls, explicit workspace/agent overrides, admitted repository request, role/team policy, and repository defaults. Workspace autonomy and the consent floor are authoritative. Repository policy can narrow access but cannot widen the workspace's effective authority. ## Compatibility and migration New modules must be schema-native. Existing modules may enter through one normalization adapter that compiles legacy sources into this manifest. The nine Hubs consume only the normalized admitted contract; Hub-specific legacy logic is prohibited. Migration metadata records source authority, adapter kind and version, conformance level, field provenance, missing fields, compatibility warnings, legacy entry points, replacement contracts, state/config migrations, parity evidence, and rollback. Supported conformance levels are: - `legacy_observed`; - `manifest_shimmed`; - `binding_managed`; - `hub_native`; - `schema_native`. Cutover requires equal or stricter permissions, stable capability IDs, preserved config/state, equivalent visible contributions, secret isolation, current health, successful app mounting where applicable, and a verified rollback. Adapters remain until native/adapted parity fixtures pass. ## Failure and recovery - Invalid schema or digest: reject admission; preserve the last admitted revision without treating it as the current desired revision. - Missing required need: block the affected module/capability. Missing optional need: apply the declared degradation and expose a sanitized reason. - Stale generation or health: withdraw the affected projection until current reconciliation succeeds. - Unknown capability: quarantine and default-deny. - Adapter or migration failure: enter `migration_blocked` or `rollback_active` and retain the verified previous binding. - Runner failure: report sanitized health/log references, execute only an allowlisted rollback, and never expose resolved secret material. ## Conformance At minimum, implementations must prove the bundled fixtures: - a passive module without an expert is valid; - an agent-routable module with a `repo_expert` is valid; - an agent-routable module without a `repo_expert` is invalid; - a resolved secret field is invalid; - an MCP-authoritative tool is invalid because MCP is only a generated view. Cross-spec acceptance adds an AI-Collab fixture that admits one PRD-enabled repository, renders its catalog in the nine Hubs, routes one permitted read-only knowledge/tool call, withholds denied or stale capabilities, resolves provider readiness without exposing secrets, and rolls back one migrated binding. ## Traceability - Requirements: `PRD-010`, requirements `PRD-REQ-073` through `PRD-REQ-084`. - Architecture: `ARCH-010`. - Implementation plan: `IMP-011`. - Related portable workspace ownership: `BR-REQ-027`, `BR-REQ-028`. - Existing service declaration seed: `wiki/integrations/repository-service-manifest.md` and `templates/services.json`.