Source Catalog

Status: Draft (Extension — v1.1 Preview)
Last Updated: 2026-02-26
Not required for ACGP v1.0 Standard or Safety-Critical conformance.

Abstract

The Source Catalog extension defines a public capability hook for evidence-grounding workloads. It standardizes negotiation metadata, attestation boundaries, and a minimal query contract used by source-match evaluators without requiring open catalog interoperability or public source disclosure.

Key Concepts (Preview)

• Public capability, private internals: Extension ID, version, visibility, and attestation are public; backing systems and payload semantics MAY remain private.
• Deployment choice: Implementations MAY use proprietary catalogs, federated catalogs, or no catalog at all.
• Opaque policy binding: Public artifacts MAY reference opaque policy handles or attestations instead of public source lineage.
• Optional scorer fallback: If the capability is absent or a query fails, optional source-match scorers follow the unavailable-and-redistribute rule defined by ACGP-3.

Hook Point

Core hook in ACGP-3 via SourceCatalog interface.

Status

Implementations MAY provide this interface. If not provided, optional source-match scorers are marked unavailable and their weights are redistributed as defined by ACGP-3. Conformance does not require a shared catalog service, open source registry, or public source lineage.

Interface Signature

from typing import Protocol, List, Optional
from dataclasses import dataclass

@dataclass
class SourceEntry:
    id: str
    category: str             # e.g., "regulatory", "market_data"
    jurisdiction: Optional[str]
    trust_score: float        # 0.0–1.0
    freshness_hours: float
    integrity_hash: str

class SourceCatalog(Protocol):
    """Source catalog capability hook for evidence grounding."""

    def query(
        self,
        categories: List[str],
        min_trust: float = 0.0,
        jurisdiction: Optional[str] = None,
        max_age_hours: Optional[float] = None,
    ) -> List[SourceEntry]: ...

    def verify(self, source_id: str) -> bool: ...

Negotiation Model [NORMATIVE]

Portable artifacts SHOULD negotiate the Source Catalog extension through an extension descriptor such as:

extensions:
  required:
    - { id: "urn:acgp:ext:source-catalog-private@1", visibility: private, enforcement_scope: remote, fail_mode: reject_activation, attestation: { digest: "sha256:...", issued_by: "did:example:steward" } }

The public protocol standardizes only the descriptor metadata and attestation shape. Catalog contents, document locators, clause references, ranking logic, and provenance chains MAY remain private.

When enforcement_scope: remote is used, SDKs MUST preserve and negotiate the descriptor and MAY still activate a bundle locally while the remote authoritative enforcer performs evidence evaluation. Optional local source-match scorers follow the unavailable-and-redistribute rule instead of returning a neutral 0.5. If source evidence is encoded as a required control with fail_mode: deny or equivalent tripwire semantics, that explicit failure path remains authoritative.

Reserved Wire Field

Field	Type	Location	Description
source_catalog	object	EVAL payload	Optional public metadata attached to evaluation results

Minimal Forward-Compatible Example

{
    "trace_id": "trace-12345",
    "blueprint_id": "finance_qa@2.1",
    "governance_tier": "GT-2",
    "ctq_dimensions": {
        "reasoning_quality": {
            "score": 0.91,
            "weight": 0.25,
            "status": "evaluated",
            "contributors": ["rationale_clarity", "plan_completeness"]
        },
        "knowledge_grounding": {
            "score": 0.88,
            "weight": 0.20,
            "status": "evaluated",
            "contributors": ["citation_coverage"]
        },
        "ethical_alignment": {
            "score": 0.94,
            "weight": 0.20,
            "status": "evaluated",
            "contributors": ["fairness_review"]
        },
        "tool_safety": {
            "score": 0.90,
            "weight": 0.20,
            "status": "evaluated",
            "contributors": ["permission_check"]
        },
        "context_awareness": {
            "score": 0.87,
            "weight": 0.15,
            "status": "evaluated",
            "contributors": ["situational_fit"]
        }
    },
    "ctq_score": 0.901,
    "risk_score": 0.099,
    "tripwires_triggered": [],
    "intervention": "ok",
    "flagged": false,
    "runtime_posture": "normal",
    "review_required": false,
    "trust_debt": {
        "provider_id": "acgp.core.default@1",
        "pre": 0.0,
        "delta": 0.0,
        "post": 0.0,
        "thresholds_crossed": []
    },
    "source_catalog": {
        "extension_id": "urn:acgp:ext:source-catalog-private@1",
        "policy_handle": "ph:9f1c2ab7",
        "attestation": {
            "digest": "sha256:...",
            "issued_by": "did:example:steward"
        }
    }
}

Public artifacts MUST NOT be required to expose source document IDs, clause locators, internal source mappings, or derivation provenance in order to negotiate or conform.