xrefkit 0.3.0__py3-none-any.whl

xrefkit/resource_provider.py

@@ -0,0 +1,187 @@
+"""Mode-aware resource providers for XID resolution."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Protocol
+from importlib import resources
+
+
+ProviderKind = Literal["repository", "instance", "content_pack", "package", "mcp"]
+ResolverMode = Literal["repository", "installed", "mcp_only", "mcp_server"]
+XID_RE = re.compile(r"<!--\s*xid:\s*([A-Fa-f0-9]{12})\s*-->")
+
+
+def _hash_bytes(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+@dataclass(frozen=True)
+class Resource:
+    xid: str
+    body: str
+    content_hash: str
+    provider: str
+    provider_kind: ProviderKind
+    path: str | None = None
+
+
+class ResourceProvider(Protocol):
+    name: str
+    kind: ProviderKind
+
+    def get(self, xid: str) -> Resource | None: ...
+
+
+class DirectoryProvider:
+    def __init__(self, name: str, kind: ProviderKind, root: str | Path) -> None:
+        self.name = name
+        self.kind = kind
+        self.root = Path(root).resolve()
+        self._index: dict[str, Path] | None = None
+
+    def _build(self) -> dict[str, Path]:
+        index: dict[str, Path] = {}
+        for path in sorted(self.root.rglob("*.md")):
+            try:
+                prefix = path.read_text(encoding="utf-8")[:512]
+            except (OSError, UnicodeDecodeError):
+                continue
+            match = XID_RE.search(prefix)
+            if not match:
+                continue
+            xid = match.group(1).upper()
+            if xid in index:
+                raise ValueError(f"duplicate XID in provider {self.name}: {xid}")
+            index[xid] = path
+        return index
+
+    def get(self, xid: str) -> Resource | None:
+        if self._index is None:
+            self._index = self._build()
+        path = self._index.get(xid.upper())
+        if path is None:
+            return None
+        data = path.read_bytes()
+        return Resource(
+            xid=xid.upper(),
+            body=data.decode("utf-8"),
+            content_hash=_hash_bytes(data),
+            provider=self.name,
+            provider_kind=self.kind,
+            path=str(path),
+        )
+
+
+class StaticProvider:
+    def __init__(self, name: str, kind: ProviderKind, resources: dict[str, str]) -> None:
+        self.name = name
+        self.kind = kind
+        self._resources = {xid.upper(): body for xid, body in resources.items()}
+
+    def get(self, xid: str) -> Resource | None:
+        body = self._resources.get(xid.upper())
+        if body is None:
+            return None
+        return Resource(
+            xid=xid.upper(),
+            body=body,
+            content_hash=_hash_bytes(body.encode("utf-8")),
+            provider=self.name,
+            provider_kind=self.kind,
+        )
+
+
+class CompiledContractProvider(StaticProvider):
+    """Resolve compact base-runtime XIDs from installed package resources."""
+
+    @classmethod
+    def installed(cls) -> "CompiledContractProvider":
+        base = resources.files("xrefkit").joinpath("resources/base")
+        current_file = base.joinpath("current.json")
+        if not current_file.is_file():
+            raise ValueError("installed base runtime is missing current.json")
+        pointer = json.loads(current_file.read_text(encoding="utf-8"))
+        generation = str(pointer["generation"])
+        if not re.fullmatch(r"[0-9a-f]{16}", generation):
+            raise ValueError("invalid installed base runtime generation")
+        contract_file = base.joinpath("generations", generation, "contracts.json")
+        compiled = json.loads(contract_file.read_text(encoding="utf-8"))
+        obligations_by_xid: dict[str, list[dict[str, object]]] = {}
+        for obligation in compiled.get("obligations", []):
+            obligations_by_xid.setdefault(obligation["source_xid"], []).append(obligation)
+        bodies: dict[str, str] = {}
+        for source in compiled.get("sources", []):
+            xid = source["xid"]
+            bodies[xid] = json.dumps(
+                {
+                    "xid": xid,
+                    "compiled": True,
+                    "source_hash": source["source_hash"],
+                    "obligations": obligations_by_xid.get(xid, []),
+                },
+                ensure_ascii=False,
+                sort_keys=True,
+            )
+        return cls("package-base", "package", bodies)
+
+
+class ProviderResolver:
+    def __init__(
+        self,
+        mode: ResolverMode,
+        providers: list[ResourceProvider],
+        *,
+        base_xids: set[str] | None = None,
+        allowed_shadows: dict[str, str] | None = None,
+    ) -> None:
+        self.mode = mode
+        self.providers = providers
+        self.base_xids = {xid.upper() for xid in (base_xids or set())}
+        self.allowed_shadows = {xid.upper(): provider for xid, provider in (allowed_shadows or {}).items()}
+        self._validate_graph()
+
+    def _validate_graph(self) -> None:
+        kinds = [provider.kind for provider in self.providers]
+        if self.mode == "mcp_server" and "mcp" in kinds:
+            raise ValueError("MCP server resolver must not contain an MCP provider")
+        if self.mode == "mcp_only" and any(kind != "mcp" for kind in kinds):
+            raise ValueError("mcp_only resolver may contain only MCP providers")
+        if self.mode != "mcp_only" and kinds.count("mcp") > 1:
+            raise ValueError("at most one MCP fallback provider is allowed")
+        if "mcp" in kinds and kinds[-1] != "mcp":
+            raise ValueError("MCP provider must be the final fallback")
+
+    def resolve(self, xid: str) -> Resource:
+        key = xid.upper()
+        matches = [resource for provider in self.providers if (resource := provider.get(key)) is not None]
+        if not matches:
+            raise KeyError(f"unknown XID: {key}")
+        hashes = {match.content_hash for match in matches}
+        if len(hashes) == 1:
+            return matches[0]
+        if key in self.base_xids:
+            raise ValueError(f"base runtime XID conflict cannot be shadowed: {key}")
+        winner = self.allowed_shadows.get(key)
+        if winner:
+            for match in matches:
+                if match.provider == winner:
+                    return match
+            raise ValueError(f"declared shadow provider not active for {key}: {winner}")
+        names = ", ".join(match.provider for match in matches)
+        raise ValueError(f"conflicting XID {key} from providers: {names}")
+
+
+def verify_compiled_source_freshness(compiled_path: str | Path, repo_root: str | Path) -> list[str]:
+    compiled = json.loads(Path(compiled_path).read_text(encoding="utf-8"))
+    root = Path(repo_root)
+    stale: list[str] = []
+    for source in compiled.get("sources", []):
+        path = root / source["path"]
+        if not path.is_file() or _hash_bytes(path.read_bytes()) != source["source_hash"]:
+            stale.append(source["xid"])
+    return stale

xrefkit/resources/base/contracts.json

@@ -0,0 +1,178 @@
+{
+  "schema": "xrefkit.compiled_runtime/v1",
+  "profile": "model-compact",
+  "compiler_version": 1,
+  "manifest_path": "docs\\core\\contracts\\base_runtime_manifest.yaml",
+  "manifest_hash": "9edce0a8e59b57651c97c2b90ee7ed5769bc462f15874d6ad67cc3b27dda0759",
+  "approval": {
+    "status": "accepted",
+    "owner": "repository_owner",
+    "approved_on": "2026-07-10",
+    "reference": "user-directed execution of design 087"
+  },
+  "estimator": {
+    "id": "chars_div_4",
+    "version": 1
+  },
+  "budgets": {
+    "l0_tokens": 2500,
+    "l1_tokens": 6000,
+    "selected_context_tokens": 12000
+  },
+  "sources": [
+    {
+      "xid": "0B5C58B5E5B2",
+      "path": "agent/000_agent_entry.md",
+      "source_hash": "e529eb32397297bb3eda2bf8a3d353b93d6283d7fed3ddcdf74905991cefe744"
+    },
+    {
+      "xid": "5A1C8E4D2F90",
+      "path": "docs/core/models/017_base_and_xref_layering.md",
+      "source_hash": "147c05288aae0212ba90e37adfd9f3c47d899c05f0a01222ce06949090f01d89"
+    },
+    {
+      "xid": "6C0B62D6366A",
+      "path": "docs/core/contracts/011_startup_xref_routing.md",
+      "source_hash": "ed8a211759051121ee2f049207fc079e5b50247f9995cc7bbb38a748e2964d09"
+    },
+    {
+      "xid": "8A666C1FD121",
+      "path": "docs/core/contracts/016_uncertainty_protocol.md",
+      "source_hash": "6fa3513c71bff7660394cc5cfc1b6c90de1d50d30f43eb0e6341699559fddc6a"
+    },
+    {
+      "xid": "A7F3C92D4E11",
+      "path": "docs/core/contracts/053_context_direction_security_guard.md",
+      "source_hash": "7f1ad91351820bcf60569245fcff86c36be1e41b6e1345057051cf524d911a70"
+    },
+    {
+      "xid": "4A423E72D2ED",
+      "path": "docs/core/contracts/015_shared_memory_operations.md",
+      "source_hash": "7972b9d813c57a3ea4901949236d600591ac766544ae426771e391f64312881f"
+    },
+    {
+      "xid": "B7A2C94F0E61",
+      "path": "docs/core/contracts/058_skill_operating_contract.md",
+      "source_hash": "5d0582dc38dc5e127590393e66b0d0ccd9b21446b58d3122b89d0ddfedb5bc03"
+    },
+    {
+      "xid": "C3A1F78D9B22",
+      "path": "docs/core/contracts/080_xrefkit_startup_contract.md",
+      "source_hash": "f6572d733b0b77e972af9538c7f9f4e03b7fb35dc5ffcd9e24c8a218c9fb755f"
+    }
+  ],
+  "obligations": [
+    {
+      "id": "skill.os_contract_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "New Skills include the Skill operating contract."
+    },
+    {
+      "id": "skill.run_first",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Start Skill execution through the runtime envelope before loading the Skill body."
+    },
+    {
+      "id": "skill.workitem_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Record concrete work items before closure."
+    },
+    {
+      "id": "skill.artifact_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Record output and evidence artifacts before closure."
+    },
+    {
+      "id": "skill.concern_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Record closure-relevant unknowns, risks, and judgments."
+    },
+    {
+      "id": "skill.verify_separate",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Advance check through deterministic verification, not the producer context."
+    },
+    {
+      "id": "work.log_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Write execution logs and retrospectives under work."
+    },
+    {
+      "id": "work.date_prefix",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Use date-prefixed work-record filenames."
+    },
+    {
+      "id": "work.session_before_complete",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Update a session log before completion, commit, or push."
+    },
+    {
+      "id": "work.promote_stable",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Promote stabilized facts and decisions to canonical locations."
+    },
+    {
+      "id": "uncertainty.explicit",
+      "source_xid": "8A666C1FD121",
+      "level": "must",
+      "statement": "Classify and expose material uncertainty, search Knowledge, and pause risky work."
+    },
+    {
+      "id": "claims.no_unsupported_fact",
+      "source_xid": "8A666C1FD121",
+      "level": "must",
+      "statement": "Do not present unsupported claims as facts; expose the evidence gap and route material uncertainty through the uncertainty protocol."
+    },
+    {
+      "id": "memory.write",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Write logs after significant discussions, decisions, or work sessions."
+    },
+    {
+      "id": "memory.session",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Ensure a work session entry exists before final response."
+    },
+    {
+      "id": "memory.before_publish",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Update logs before commit or push."
+    },
+    {
+      "id": "memory.promote",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Promote stabilized work content into canonical docs or Knowledge."
+    },
+    {
+      "id": "memory.filename",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Prefix work record filenames with the date."
+    }
+  ],
+  "conditional_loads": [
+    {
+      "xid": "B7A2C94F0E61",
+      "when": "skill_execution"
+    }
+  ],
+  "lint_candidates": [],
+  "model_body_hash": "5251a22001428241b90e7edc34867462de36f3eb048720a7e6f175f4679b3def",
+  "estimated_tokens": 418,
+  "release_ready": true
+}

xrefkit/resources/base/current.json

@@ -0,0 +1,6 @@
+{
+  "schema": "xrefkit.base_generation/v1",
+  "generation": "7a682a5272907354",
+  "contracts": "generations/7a682a5272907354/contracts.json",
+  "model_body": "generations/7a682a5272907354/model_body.md"
+}

xrefkit/resources/base/generations/7a682a5272907354/contracts.json

@@ -0,0 +1,178 @@
+{
+  "schema": "xrefkit.compiled_runtime/v1",
+  "profile": "model-compact",
+  "compiler_version": 1,
+  "manifest_path": "docs\\core\\contracts\\base_runtime_manifest.yaml",
+  "manifest_hash": "9edce0a8e59b57651c97c2b90ee7ed5769bc462f15874d6ad67cc3b27dda0759",
+  "approval": {
+    "status": "accepted",
+    "owner": "repository_owner",
+    "approved_on": "2026-07-10",
+    "reference": "user-directed execution of design 087"
+  },
+  "estimator": {
+    "id": "chars_div_4",
+    "version": 1
+  },
+  "budgets": {
+    "l0_tokens": 2500,
+    "l1_tokens": 6000,
+    "selected_context_tokens": 12000
+  },
+  "sources": [
+    {
+      "xid": "0B5C58B5E5B2",
+      "path": "agent/000_agent_entry.md",
+      "source_hash": "e529eb32397297bb3eda2bf8a3d353b93d6283d7fed3ddcdf74905991cefe744"
+    },
+    {
+      "xid": "5A1C8E4D2F90",
+      "path": "docs/core/models/017_base_and_xref_layering.md",
+      "source_hash": "147c05288aae0212ba90e37adfd9f3c47d899c05f0a01222ce06949090f01d89"
+    },
+    {
+      "xid": "6C0B62D6366A",
+      "path": "docs/core/contracts/011_startup_xref_routing.md",
+      "source_hash": "ed8a211759051121ee2f049207fc079e5b50247f9995cc7bbb38a748e2964d09"
+    },
+    {
+      "xid": "8A666C1FD121",
+      "path": "docs/core/contracts/016_uncertainty_protocol.md",
+      "source_hash": "6fa3513c71bff7660394cc5cfc1b6c90de1d50d30f43eb0e6341699559fddc6a"
+    },
+    {
+      "xid": "A7F3C92D4E11",
+      "path": "docs/core/contracts/053_context_direction_security_guard.md",
+      "source_hash": "7f1ad91351820bcf60569245fcff86c36be1e41b6e1345057051cf524d911a70"
+    },
+    {
+      "xid": "4A423E72D2ED",
+      "path": "docs/core/contracts/015_shared_memory_operations.md",
+      "source_hash": "7972b9d813c57a3ea4901949236d600591ac766544ae426771e391f64312881f"
+    },
+    {
+      "xid": "B7A2C94F0E61",
+      "path": "docs/core/contracts/058_skill_operating_contract.md",
+      "source_hash": "5d0582dc38dc5e127590393e66b0d0ccd9b21446b58d3122b89d0ddfedb5bc03"
+    },
+    {
+      "xid": "C3A1F78D9B22",
+      "path": "docs/core/contracts/080_xrefkit_startup_contract.md",
+      "source_hash": "f6572d733b0b77e972af9538c7f9f4e03b7fb35dc5ffcd9e24c8a218c9fb755f"
+    }
+  ],
+  "obligations": [
+    {
+      "id": "skill.os_contract_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "New Skills include the Skill operating contract."
+    },
+    {
+      "id": "skill.run_first",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Start Skill execution through the runtime envelope before loading the Skill body."
+    },
+    {
+      "id": "skill.workitem_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Record concrete work items before closure."
+    },
+    {
+      "id": "skill.artifact_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Record output and evidence artifacts before closure."
+    },
+    {
+      "id": "skill.concern_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Record closure-relevant unknowns, risks, and judgments."
+    },
+    {
+      "id": "skill.verify_separate",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Advance check through deterministic verification, not the producer context."
+    },
+    {
+      "id": "work.log_required",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Write execution logs and retrospectives under work."
+    },
+    {
+      "id": "work.date_prefix",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Use date-prefixed work-record filenames."
+    },
+    {
+      "id": "work.session_before_complete",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Update a session log before completion, commit, or push."
+    },
+    {
+      "id": "work.promote_stable",
+      "source_xid": "0B5C58B5E5B2",
+      "level": "must",
+      "statement": "Promote stabilized facts and decisions to canonical locations."
+    },
+    {
+      "id": "uncertainty.explicit",
+      "source_xid": "8A666C1FD121",
+      "level": "must",
+      "statement": "Classify and expose material uncertainty, search Knowledge, and pause risky work."
+    },
+    {
+      "id": "claims.no_unsupported_fact",
+      "source_xid": "8A666C1FD121",
+      "level": "must",
+      "statement": "Do not present unsupported claims as facts; expose the evidence gap and route material uncertainty through the uncertainty protocol."
+    },
+    {
+      "id": "memory.write",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Write logs after significant discussions, decisions, or work sessions."
+    },
+    {
+      "id": "memory.session",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Ensure a work session entry exists before final response."
+    },
+    {
+      "id": "memory.before_publish",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Update logs before commit or push."
+    },
+    {
+      "id": "memory.promote",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Promote stabilized work content into canonical docs or Knowledge."
+    },
+    {
+      "id": "memory.filename",
+      "source_xid": "4A423E72D2ED",
+      "level": "must",
+      "statement": "Prefix work record filenames with the date."
+    }
+  ],
+  "conditional_loads": [
+    {
+      "xid": "B7A2C94F0E61",
+      "when": "skill_execution"
+    }
+  ],
+  "lint_candidates": [],
+  "model_body_hash": "5251a22001428241b90e7edc34867462de36f3eb048720a7e6f175f4679b3def",
+  "estimated_tokens": 418,
+  "release_ready": true
+}

xrefkit/resources/base/generations/7a682a5272907354/model_body.md

@@ -0,0 +1,22 @@
+# XRefKit Base Runtime Contract
+
+- [must] skill.os_contract_required: New Skills include the Skill operating contract.
+- [must] skill.run_first: Start Skill execution through the runtime envelope before loading the Skill body.
+- [must] skill.workitem_required: Record concrete work items before closure.
+- [must] skill.artifact_required: Record output and evidence artifacts before closure.
+- [must] skill.concern_required: Record closure-relevant unknowns, risks, and judgments.
+- [must] skill.verify_separate: Advance check through deterministic verification, not the producer context.
+- [must] work.log_required: Write execution logs and retrospectives under work.
+- [must] work.date_prefix: Use date-prefixed work-record filenames.
+- [must] work.session_before_complete: Update a session log before completion, commit, or push.
+- [must] work.promote_stable: Promote stabilized facts and decisions to canonical locations.
+- [must] uncertainty.explicit: Classify and expose material uncertainty, search Knowledge, and pause risky work.
+- [must] claims.no_unsupported_fact: Do not present unsupported claims as facts; expose the evidence gap and route material uncertainty through the uncertainty protocol.
+- [must] memory.write: Write logs after significant discussions, decisions, or work sessions.
+- [must] memory.session: Ensure a work session entry exists before final response.
+- [must] memory.before_publish: Update logs before commit or push.
+- [must] memory.promote: Promote stabilized work content into canonical docs or Knowledge.
+- [must] memory.filename: Prefix work record filenames with the date.
+
+Conditional loads:
+- skill_execution: xid B7A2C94F0E61