# RMGR-ARCH-CMD-0001
id: RMGR-ARCH-CMD-0001
contract_id: helixforge.repo-manager
contract_version: "0.1.0"
status: draft-reviewable
created: "2026-08-09"
document: docs/observation-command-contracts_v0.1.md
representation_ref: RMGR-ARCH-REP-0001
workplan_task: RMGR-WP-0001-T02

rules:
  - no_orm_in_public_dtos
  - applied_file_commands_require_git_sha
  - authz_before_mutation
  - dual_write_same_fact_forbidden
  - secrets_never_in_events

common_envelope_fields:
  - api_version
  - correlation_id
  - request_id
  - actor
  - authz

idempotency:
  commands:
    key: idempotency_key
    retention: ">=24h"
    same_key_different_payload: conflict

evidence_fields:
  - status  # accepted | applied | rejected | failed
  - git_sha
  - git_refs
  - forge_pr_url
  - files_touched
  - content_hashes
  - observed_at
  - notes

error_codes:
  - unauthorized
  - not_found
  - conflict
  - precondition_failed
  - validation_error
  - policy_denied
  - unavailable
  - internal

scopes:
  - repo:read
  - repo:register
  - repo:reconcile
  - repo:command:work_status
  - repo:command:writeback_ids
  - repo:command:lifecycle
  - repo:command:agent_assign
  - repo:admin

observation:
  fact_types:
    - RepositorySnapshot
    - WorkRecordIndexEntry
    - ConsistencyFinding
    - RevisionObservation
    - AgentAssignment
    - SignalSet
  operations:
    - id: GetRepository
      port: port.repo
      scope: repo:read
    - id: ListRepositories
      port: port.repo
      scope: repo:read
    - id: ObserveRevision
      port: port.repo
      scope: repo:read
    - id: ListWorkRecords
      port: port.work
      scope: repo:read
    - id: GetWorkRecord
      port: port.work
      scope: repo:read
    - id: ListFindings
      port: port.repo
      scope: repo:read
    - id: GetSignals
      port: port.repo
      scope: repo:read

commands:
  lifecycle_states: [accepted, running, applied, rejected, failed]
  catalog:
    - type: repo.register
      scope: repo:register
      mutates_git: false
    - type: repo.set_host_path
      scope: repo:register
      mutates_git: false
    - type: repo.set_lifecycle
      scope: repo:command:lifecycle
      mutates_git: false
    - type: repo.reconcile
      scope: repo:reconcile
      mutates_git: false
    - type: repo.rebuild_index
      scope: repo:reconcile
      mutates_git: false
    - type: repo.work.update_task_status
      scope: repo:command:work_status
      mutates_git: true
      params: [task_id, status, blocking_reason]
    - type: repo.work.update_workplan_status
      scope: repo:command:work_status
      mutates_git: true
      params: [workplan_id, status]
    - type: repo.work.writeback_ids
      scope: repo:command:writeback_ids
      mutates_git: true
    - type: repo.agents.assign
      scope: repo:command:agent_assign
      mutates_git: preferred

events_emitted:
  - repo.registered
  - repo.observed
  - repo.reconciled
  - repo.command.applied
  - repo.command.failed
  - repo.work.indexed
  - repo.drift.detected

hub_core:
  ports: [port.repo, port.work]
  must_not:
    - open_repo_manager_db
    - import_orm_models
    - dual_write_work_status_without_command_evidence

conformance_min:
  - C1_dto_no_orm
  - C2_reconcile_idempotent
  - C3_command_idempotency_key
  - C4_stale_head_precondition
  - C5_scope_deny
  - C6_applied_has_git_sha
  - C7_rebuild_index
  - C8_events_correlation_no_secrets