# ============================================================
# src/accountable_record/stage_020_contract/base/constants.py
# ============================================================
"""Contract-stage constants and diagnostic codes (Layer 0).

WHY:
    Stage 020 establishes the *contract context* of the target repository:
    which Accountable Record (AR) contract the repository targets, at which
    version, and whether that declaration coheres with the identity already
    established by stage 010. This module is the stage's Layer 0 vocabulary:
    constant filenames/keys plus the AR.CT.* diagnostic codes so
    every 020 op/validation module shares one set of names, exactly as the
    AR.ID.* codes are shared across stage 010.

OBS:
    Like stage 010's constants, any schema-or-filesystem read here is lazy (a
    function call), never import-time, so importing this module can never do
    I/O or raise. The contract version, when present, is NOT canonical at this
    stage: per AR policy CITATION.cff remains the sole canonical version source
    (stage 010 owns that check). Stage 020 only checks that a contract version,
    if declared in the manifest, agrees with the identity version stage 010
    already accepted. It never re-derives canonical version authority.

REQ:
    - No internal dependencies beyond the shared Layer 0 diagnostics module.
    - Concern is Concern.CONTRACT ("CT"), already defined in the shared
      diagnostics enum; 020 does not mint new concerns.
    - Diagnostic codes are AR-owned: ar_code(Concern.CONTRACT, NAME).
"""

STAGE_NAME = "stage_020_contract"

# WHY: the manifest is where a repository declares the contract it targets.
#      The filename set is owned by se-manifest-schema (stage 010 resolves the
#      allowed names); 020 references the canonical default only as an anchor
#      for diagnostics and never hardcodes the allowed set.
MANIFEST_FILENAME = "SE_MANIFEST.toml"

DEFAULT_CANONICAL_VERSION_FILE = "CITATION.cff"
"""Default canonical version source for non-contract repositories.

OBS:
    For implementation and other non-contract repositories, CITATION.cff is the
    canonical repository identity version source. Contract/specification
    repositories may use SE_MANIFEST.toml as the canonical version source,
    interpreted through the manifest schema. Stage 020 should therefore resolve
    canonical version authority from repository context rather than treating one
    filename as universal.
"""

CONTRACT_CANONICAL_VERSION_FILE = MANIFEST_FILENAME
"""Canonical version source for AR contract/specification repositories.

OBS:
    For the real Accountable Record contract repository, canonical version
    authority is the manifest, read according to the schema TOML. This is not
    the default for implementation repositories such as accountable-record-py.
"""


# Manifest table/keys that carry the contract declaration.
# OBS: these are the *structural* keys 020 reads. They are intentionally
#      named here as one place so a manifest-schema change is a one-line edit.
CONTRACT_TABLE = "contract"
CONTRACT_KEY_NAME = "name"
CONTRACT_KEY_VERSION = "version"
CONTRACT_KEY_SPEC = "spec"

# WHY: the contract this implementation provides/consumes. A target repository
#      declaring AR conformance is expected to name this contract. The literal
#      is the AR spec identifier, not a package name.
EXPECTED_CONTRACT_NAME = "accountable-record"

# The Structural Explainability specification that AR conforms to. Per
# AR.CONFORMANCE.SE.REQUIRED, any AR-conformant system also conforms to SE;
# stage 020 records the declared SE relationship without asserting it is met.
SE_SPEC_NAME = "structural-explainability"
