xrefkit 0.3.0__py3-none-any.whl

xrefkit/registry.py

@@ -0,0 +1,334 @@
+"""In-memory registries for XRefKit v2 MVP."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .models import LocalDomainSkill, LocalManifest, PackageManifest, SkillDefinition
+
+
+def _contained_path(root: Path, relative_path: str, *, label: str) -> Path:
+    root = root.resolve()
+    candidate = (root / relative_path).resolve()
+    try:
+        candidate.relative_to(root)
+    except ValueError as exc:
+        raise ValueError(f"{label} escapes root: {relative_path}") from exc
+    return candidate
+
+
+@dataclass(frozen=True)
+class XidAssetRecord:
+    xid: str
+    path: Path
+    root: Path
+    source_type: str
+    asset_type: str
+    includeable: bool = False
+    package_id: str | None = None
+    local_id: str | None = None
+    fragment_id: str | None = None
+
+
+@dataclass(frozen=True)
+class PackageRecord:
+    manifest: PackageManifest
+    root: Path
+
+
+@dataclass(frozen=True)
+class SkillRecord:
+    package_id: str | None
+    skill_id: str
+    xid: str
+    definition: SkillDefinition | LocalDomainSkill
+    path: Path
+    root: Path
+    source_type: str
+    local_id: str | None = None
+
+
+@dataclass(frozen=True)
+class KnowledgeRecord:
+    id: str
+    xid: str
+    path: Path
+    source_type: str
+    package_id: str | None = None
+    local_id: str | None = None
+
+
+class XidRegistry:
+    def __init__(self) -> None:
+        self._items: dict[str, object] = {}
+
+    def add(self, xid: str, record: object) -> None:
+        if xid in self._items:
+            raise ValueError(f"duplicate XID: {xid}")
+        self._items[xid] = record
+
+    def add_if_absent(self, xid: str, record: object) -> None:
+        if xid not in self._items:
+            self._items[xid] = record
+
+    def get(self, xid: str) -> object | None:
+        return self._items.get(xid)
+
+    def require(self, xid: str) -> object:
+        record = self.get(xid)
+        if record is None:
+            raise KeyError(f"unknown XID: {xid}")
+        return record
+
+    def require_asset(self, xid: str) -> XidAssetRecord:
+        record = self.require(xid)
+        if not isinstance(record, XidAssetRecord):
+            raise TypeError(f"XID is not a file-backed asset: {xid}")
+        return record
+
+    def __contains__(self, xid: str) -> bool:
+        return xid in self._items
+
+
+class PackageRegistry:
+    def __init__(self) -> None:
+        self._packages: dict[str, PackageRecord] = {}
+
+    def add(self, manifest: PackageManifest, root: str | Path) -> PackageRecord:
+        if manifest.package_id in self._packages:
+            raise ValueError(f"duplicate package_id: {manifest.package_id}")
+        record = PackageRecord(manifest=manifest, root=Path(root))
+        self._packages[manifest.package_id] = record
+        return record
+
+    def get(self, package_id: str) -> PackageRecord | None:
+        return self._packages.get(package_id)
+
+    def require(self, package_id: str) -> PackageRecord:
+        record = self.get(package_id)
+        if record is None:
+            raise KeyError(f"unknown package_id: {package_id}")
+        return record
+
+    def list(self) -> list[PackageRecord]:
+        return list(self._packages.values())
+
+
+class SkillRegistry:
+    def __init__(self) -> None:
+        self._skills: dict[str, SkillRecord] = {}
+
+    def add(self, record: SkillRecord) -> None:
+        if record.skill_id in self._skills:
+            raise ValueError(f"duplicate skill_id: {record.skill_id}")
+        self._skills[record.skill_id] = record
+
+    def get(self, skill_id: str) -> SkillRecord | None:
+        return self._skills.get(skill_id)
+
+    def require(self, skill_id: str) -> SkillRecord:
+        record = self.get(skill_id)
+        if record is None:
+            raise KeyError(f"unknown skill_id: {skill_id}")
+        return record
+
+    def list(self) -> list[SkillRecord]:
+        return list(self._skills.values())
+
+
+class KnowledgeRegistry:
+    def __init__(self) -> None:
+        self._knowledge: dict[str, KnowledgeRecord] = {}
+
+    def add(self, record: KnowledgeRecord) -> None:
+        if record.id in self._knowledge:
+            raise ValueError(f"duplicate knowledge id: {record.id}")
+        self._knowledge[record.id] = record
+
+    def list(self) -> list[KnowledgeRecord]:
+        return list(self._knowledge.values())
+
+
+class XRefKitRegistry:
+    def __init__(self) -> None:
+        self.packages = PackageRegistry()
+        self.skills = SkillRegistry()
+        self.knowledge = KnowledgeRegistry()
+        self.xids = XidRegistry()
+
+    def add_package(self, manifest: PackageManifest, root: str | Path) -> PackageRecord:
+        root = Path(root)
+        package = self.packages.add(manifest, root)
+        package_assets = (
+            ("skill", manifest.provides.skills),
+            ("fragment", manifest.provides.fragments),
+            ("knowledge", manifest.provides.knowledge),
+            ("review_axis", manifest.provides.review_axes),
+            ("schema", manifest.provides.schemas),
+            ("template", manifest.provides.templates),
+        )
+        for asset_type, assets in package_assets:
+            for asset in assets:
+                self.xids.add(
+                    asset.xid,
+                    XidAssetRecord(
+                        xid=asset.xid,
+                        path=root / asset.path,
+                        root=root,
+                        source_type="package",
+                        asset_type=asset_type,
+                        includeable=asset_type == "fragment",
+                        package_id=manifest.package_id,
+                        fragment_id=asset.id,
+                    ),
+                )
+        return package
+
+    def add_package_skill(self, *, package_id: str, skill: SkillDefinition, path: str | Path, root: str | Path) -> None:
+        root = Path(root)
+        package = self.packages.require(package_id)
+        if package.root != root:
+            raise ValueError(f"package root mismatch for {package_id}")
+        self.xids.add_if_absent(
+            skill.xid,
+            XidAssetRecord(
+                xid=skill.xid,
+                path=Path(path),
+                root=root,
+                source_type="package",
+                asset_type="skill",
+                includeable=False,
+                package_id=package_id,
+                fragment_id=skill.skill_id,
+            ),
+        )
+        self.xids.add_if_absent(
+            skill.entry.xid,
+            XidAssetRecord(
+                xid=skill.entry.xid,
+                path=root / skill.entry.path,
+                root=root,
+                source_type="package",
+                asset_type="fragment",
+                includeable=False,
+                package_id=package_id,
+                fragment_id="entry",
+            ),
+        )
+        for fragment in skill.required_fragments:
+            self.xids.add_if_absent(
+                fragment.xid,
+                XidAssetRecord(
+                    xid=fragment.xid,
+                    path=root / fragment.path,
+                    root=root,
+                    source_type="package",
+                    asset_type="fragment",
+                    includeable=False,
+                    package_id=package_id,
+                    fragment_id=fragment.id,
+                ),
+            )
+        for branch in skill.branches:
+            self.xids.add_if_absent(
+                branch.xid,
+                XidAssetRecord(
+                    xid=branch.xid,
+                    path=root / branch.path,
+                    root=root,
+                    source_type="package",
+                    asset_type="fragment",
+                    includeable=False,
+                    package_id=package_id,
+                    fragment_id=branch.id,
+                ),
+            )
+        record = SkillRecord(
+            package_id=package_id,
+            skill_id=skill.skill_id,
+            xid=skill.xid,
+            definition=skill,
+            path=Path(path),
+            root=root,
+            source_type="package",
+        )
+        self.skills.add(record)
+
+    def add_package_knowledge_from_manifest(self, manifest: PackageManifest, root: str | Path) -> None:
+        root = Path(root)
+        for asset in manifest.provides.knowledge:
+            self.knowledge.add(
+                KnowledgeRecord(
+                    id=asset.id,
+                    xid=asset.xid,
+                    path=root / asset.path,
+                    source_type="package",
+                    package_id=manifest.package_id,
+                )
+            )
+
+    def add_local_manifest_assets(self, local_root: str | Path, manifest: LocalManifest) -> None:
+        local_root = Path(local_root).resolve()
+        local_assets = (
+            ("knowledge", manifest.mounts.knowledge),
+            ("template", manifest.mounts.templates),
+            ("schema", manifest.mounts.schemas),
+            ("review_axis", manifest.mounts.review_axes),
+        )
+        for asset_type, assets in local_assets:
+            for asset in assets:
+                asset_path = _contained_path(local_root, asset.path, label=f"local asset {asset.id}")
+                self.xids.add(
+                    asset.xid,
+                    XidAssetRecord(
+                        xid=asset.xid,
+                        path=asset_path,
+                        root=local_root,
+                        source_type="local",
+                        asset_type=asset_type,
+                        includeable=False,
+                        local_id=manifest.local_id,
+                        fragment_id=asset.id,
+                    ),
+                )
+        for asset in manifest.mounts.knowledge:
+            asset_path = _contained_path(local_root, asset.path, label=f"local asset {asset.id}")
+            self.knowledge.add(
+                KnowledgeRecord(
+                    id=asset.id,
+                    xid=asset.xid,
+                    path=asset_path,
+                    source_type="local",
+                    local_id=manifest.local_id,
+                )
+            )
+
+    def add_local_skill(self, *, skill: LocalDomainSkill, path: str | Path, root: str | Path, local_id: str) -> None:
+        root = Path(root).resolve()
+        path = _contained_path(root, str(path), label=f"local skill {skill.skill_id}")
+        self.xids.add(
+            skill.xid,
+            XidAssetRecord(
+                xid=skill.xid,
+                path=Path(path),
+                root=root,
+                source_type="local",
+                asset_type="skill",
+                includeable=False,
+                local_id=local_id,
+                fragment_id="local_skill",
+            ),
+        )
+        self.skills.add(
+            SkillRecord(
+                package_id=None,
+                skill_id=skill.skill_id,
+                xid=skill.xid,
+                definition=skill,
+                path=Path(path),
+                root=root,
+                source_type="local",
+                local_id=local_id,
+            )
+        )

xrefkit/resolver.py

@@ -0,0 +1,252 @@
+"""Effective Skill Bundle resolver for XRefKit v2 MVP."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .hashing import sha256_file
+from .models import (
+    BundleReferences,
+    ConflictEntry,
+    DomainKnowledgeCatalogEntry,
+    EffectiveSkillBundle,
+    LoadReason,
+    LoadedTexts,
+    LocalDomainSkill,
+    SkillDefinition,
+    SourceTraceEntry,
+    SourceType,
+    XidLoadedRef,
+)
+from .registry import SkillRecord, XidAssetRecord, XRefKitRegistry
+from .models.common import version_satisfies
+
+
+def _split_skill_ref(ref: str) -> tuple[str, str]:
+    if "::" not in ref:
+        raise ValueError(f"skill ref must use package::skill format: {ref}")
+    package_id, skill_id = ref.split("::", 1)
+    if not package_id or not skill_id:
+        raise ValueError(f"invalid skill ref: {ref}")
+    return package_id, skill_id
+
+
+def _loaded(path: Path, xid: str, reason: LoadReason) -> XidLoadedRef:
+    return XidLoadedRef(xid=xid, content_hash=sha256_file(path), load_reason=reason)
+
+
+def _trace(
+    *,
+    path: Path,
+    root: Path,
+    xid: str,
+    source_type: SourceType,
+    package_id: str | None = None,
+    local_id: str | None = None,
+    fragment_id: str | None = None,
+) -> SourceTraceEntry:
+    try:
+        rel_path = path.relative_to(root).as_posix()
+    except ValueError:
+        rel_path = path.as_posix()
+    return SourceTraceEntry(
+        source_type=source_type,
+        xid=xid,
+        path=rel_path,
+        content_hash=sha256_file(path),
+        package_id=package_id,
+        local_id=local_id,
+        fragment_id=fragment_id,
+    )
+
+
+def _trace_asset(asset: XidAssetRecord) -> SourceTraceEntry:
+    return _trace(
+        path=asset.path,
+        root=asset.root,
+        xid=asset.xid,
+        source_type=SourceType(asset.source_type),
+        package_id=asset.package_id,
+        local_id=asset.local_id,
+        fragment_id=asset.fragment_id,
+    )
+
+
+class EffectiveSkillResolver:
+    def __init__(self, registry: XRefKitRegistry) -> None:
+        self.registry = registry
+
+    def resolve_entry(self, skill_id: str) -> EffectiveSkillBundle:
+        local_record = self.registry.skills.require(skill_id)
+        if not isinstance(local_record.definition, LocalDomainSkill):
+            raise ValueError("resolve_entry expects a LocalDomainSkill")
+
+        local_skill = local_record.definition
+        extends = local_skill.xrefkit.extends[0]
+        package_id, base_skill_id = _split_skill_ref(extends.ref)
+        base_record = self.registry.skills.require(base_skill_id)
+        if base_record.package_id != package_id:
+            raise ValueError(f"extends package mismatch for {extends.ref}")
+        if base_record.xid != extends.xid:
+            raise ValueError(f"extends XID mismatch for {extends.ref}")
+        if not isinstance(base_record.definition, SkillDefinition):
+            raise ValueError("extends target must be a package SkillDefinition")
+
+        base_skill = base_record.definition
+        package = self.registry.packages.require(package_id)
+        if not version_satisfies(package.manifest.version, extends.version):
+            raise ValueError(
+                f"package version {package.manifest.version} does not satisfy {extends.version}"
+            )
+        if not package.manifest.contract.can_be_extended_by_local_skill:
+            raise ValueError(f"package does not allow local extension: {package_id}")
+        if not base_skill.extension_policy.can_be_extended_by_local_skill:
+            raise ValueError(f"Skill does not allow local extension: {base_skill.skill_id}")
+        loaded_texts = LoadedTexts()
+        source_trace: list[SourceTraceEntry] = []
+        conflicts: list[ConflictEntry] = []
+
+        self._load_includes(local_skill, loaded_texts, source_trace, conflicts)
+        self._load_base_required_texts(base_record, base_skill, loaded_texts, source_trace)
+        self._load_local_skill(local_record, local_skill, loaded_texts, source_trace)
+
+        required_outputs = self._merge_required_outputs(base_skill, local_skill)
+        references = BundleReferences(
+            supporting_skill_refs=[use.ref for use in local_skill.xrefkit.uses],
+            knowledge=list(dict.fromkeys(base_skill.required_knowledge + (local_skill.xrefkit.injects.knowledge if local_skill.xrefkit.injects else []))),
+            templates=list(dict.fromkeys([local_skill.xrefkit.output.template_xid] if local_skill.xrefkit.output and local_skill.xrefkit.output.template_xid else [])),
+            schemas=list(dict.fromkeys(base_skill.schemas + ([local_skill.xrefkit.output.schema_xid] if local_skill.xrefkit.output and local_skill.xrefkit.output.schema_xid else []))),
+            review_axes=list(dict.fromkeys(base_skill.review_axes + local_skill.xrefkit.review_axes)),
+            branches=[branch.xid for branch in base_skill.branches],
+        )
+        available_domain_knowledge = self._build_available_domain_knowledge(set(references.knowledge))
+
+        return EffectiveSkillBundle(
+            effective_skill_id=local_skill.skill_id,
+            resolution_mode="entry",
+            base_contracts=[extends.ref],
+            loaded_texts=loaded_texts,
+            references=references,
+            available_domain_knowledge=available_domain_knowledge,
+            branches_available=[
+                {
+                    "id": branch.id,
+                    "xid": branch.xid,
+                    "load_policy": branch.load_policy,
+                    "condition_summary": ", ".join(branch.condition.any_intent),
+                }
+                for branch in base_skill.branches
+            ],
+            required_outputs=required_outputs,
+            load_policy_applied="entry",
+            source_trace=source_trace,
+            conflicts=conflicts,
+        )
+
+    def _load_includes(
+        self,
+        local_skill: LocalDomainSkill,
+        loaded_texts: LoadedTexts,
+        source_trace: list[SourceTraceEntry],
+        conflicts: list[ConflictEntry],
+    ) -> None:
+        seen: set[str] = set()
+        for include in local_skill.xrefkit.includes:
+            if include.xid in seen:
+                conflicts.append(
+                    ConflictEntry(
+                        severity="info",
+                        code="include_skipped_duplicate",
+                        message=f"duplicate include skipped: {include.xid}",
+                        xids=[include.xid],
+                    )
+                )
+                continue
+            seen.add(include.xid)
+            asset = self.registry.xids.require_asset(include.xid)
+            if asset.asset_type != "fragment" or not asset.includeable:
+                raise ValueError(f"includes only accepts fragment assets; xid={include.xid}, actual asset_type={asset.asset_type}")
+            loaded_texts.included.append(_loaded(asset.path, include.xid, LoadReason.INCLUDE_FRAGMENT))
+            source_trace.append(_trace_asset(asset))
+
+    def _load_base_required_texts(
+        self,
+        base_record: SkillRecord,
+        base_skill: SkillDefinition,
+        loaded_texts: LoadedTexts,
+        source_trace: list[SourceTraceEntry],
+    ) -> None:
+        package_id = base_record.package_id
+        if package_id is None:
+            raise ValueError("base SkillDefinition must belong to a package")
+
+        entry_path = base_record.root / base_skill.entry.path
+        loaded_texts.inherited.append(_loaded(entry_path, base_skill.entry.xid, LoadReason.SKILL_ENTRY))
+        source_trace.append(
+            _trace(
+                path=entry_path,
+                root=base_record.root,
+                xid=base_skill.entry.xid,
+                source_type=SourceType.PACKAGE,
+                package_id=package_id,
+                fragment_id="entry",
+            )
+        )
+
+        for fragment in base_skill.required_fragments:
+            fragment_path = base_record.root / fragment.path
+            loaded_texts.inherited.append(_loaded(fragment_path, fragment.xid, LoadReason.REQUIRED_FRAGMENT))
+            source_trace.append(
+                _trace(
+                    path=fragment_path,
+                    root=base_record.root,
+                    xid=fragment.xid,
+                    source_type=SourceType.PACKAGE,
+                    package_id=package_id,
+                    fragment_id=fragment.id,
+                )
+            )
+
+    def _load_local_skill(
+        self,
+        local_record: SkillRecord,
+        local_skill: LocalDomainSkill,
+        loaded_texts: LoadedTexts,
+        source_trace: list[SourceTraceEntry],
+    ) -> None:
+        loaded_texts.local.append(_loaded(local_record.path, local_skill.xid, LoadReason.LOCAL_SKILL))
+        source_trace.append(
+            _trace(
+                path=local_record.path,
+                root=local_record.root,
+                xid=local_skill.xid,
+                source_type=SourceType.LOCAL,
+                local_id=local_record.local_id or local_record.root.name,
+                fragment_id="local_skill",
+            )
+        )
+
+    def _merge_required_outputs(self, base_skill: SkillDefinition, local_skill: LocalDomainSkill) -> list[str]:
+        merged = list(dict.fromkeys(base_skill.required_outputs + local_skill.xrefkit.required_outputs))
+        missing = set(base_skill.required_outputs) - set(merged)
+        if missing:
+            raise ValueError(f"local skill weakened required_outputs: {sorted(missing)}")
+        return merged
+
+    def _build_available_domain_knowledge(self, selected_xids: set[str]) -> list[DomainKnowledgeCatalogEntry]:
+        entries: list[DomainKnowledgeCatalogEntry] = []
+        for record in self.registry.knowledge.list():
+            selected = record.xid in selected_xids
+            entries.append(
+                DomainKnowledgeCatalogEntry(
+                    id=record.id,
+                    xid=record.xid,
+                    source_type=SourceType(record.source_type),
+                    content_hash=sha256_file(record.path),
+                    selected=selected,
+                    package_id=record.package_id,
+                    local_id=record.local_id,
+                    selection_reason="referenced_by_effective_skill" if selected else None,
+                )
+            )
+        return entries