xrefkit 0.3.0__py3-none-any.whl

xrefkit/models/local_manifest.py

@@ -0,0 +1,217 @@
+"""Pydantic models for Project Local manifests and domain skill wrappers."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import Field, field_validator, model_validator
+
+from .common import StrictModel, validate_non_empty, validate_package_id, validate_xid
+
+
+class RequiredSkillPackage(StrictModel):
+    package_id: str
+    version: str
+
+    @field_validator("package_id")
+    @classmethod
+    def _validate_package_id(cls, value: str) -> str:
+        return validate_package_id(value)
+
+    @field_validator("version")
+    @classmethod
+    def _validate_version(cls, value: str) -> str:
+        return validate_non_empty(value, "version")
+
+
+class LocalRequires(StrictModel):
+    xrefkit_core: str
+    skill_packages: list[RequiredSkillPackage]
+
+    @field_validator("xrefkit_core")
+    @classmethod
+    def _validate_core_constraint(cls, value: str) -> str:
+        return validate_non_empty(value, "xrefkit_core")
+
+    @field_validator("skill_packages")
+    @classmethod
+    def _validate_skill_packages(cls, values: list[RequiredSkillPackage]) -> list[RequiredSkillPackage]:
+        if not values:
+            raise ValueError("requires.skill_packages must not be empty")
+        package_ids = [item.package_id for item in values]
+        if len(package_ids) != len(set(package_ids)):
+            raise ValueError("requires.skill_packages contains duplicate package_id values")
+        return values
+
+
+class LocalSkillMount(StrictModel):
+    path: str
+
+    @field_validator("path")
+    @classmethod
+    def _validate_path(cls, value: str) -> str:
+        return validate_non_empty(value, "path")
+
+
+class LocalAssetMount(StrictModel):
+    id: str
+    xid: str
+    path: str
+
+    @field_validator("id", "path")
+    @classmethod
+    def _validate_non_empty(cls, value: str) -> str:
+        return validate_non_empty(value, "value")
+
+    @field_validator("xid")
+    @classmethod
+    def _validate_xid(cls, value: str) -> str:
+        return validate_xid(value)
+
+
+class LocalMounts(StrictModel):
+    skills: list[LocalSkillMount] = Field(default_factory=list)
+    knowledge: list[LocalAssetMount] = Field(default_factory=list)
+    templates: list[LocalAssetMount] = Field(default_factory=list)
+    schemas: list[LocalAssetMount] = Field(default_factory=list)
+    review_axes: list[LocalAssetMount] = Field(default_factory=list)
+
+
+class LocalMergePolicy(StrictModel):
+    can_extend_core: bool = True
+    can_weaken_core: bool = False
+    can_weaken_pack_contract: bool = False
+
+    @model_validator(mode="after")
+    def _enforce_mvp_policy(self) -> "LocalMergePolicy":
+        if self.can_weaken_core:
+            raise ValueError("Project Local cannot weaken Core")
+        if self.can_weaken_pack_contract:
+            raise ValueError("Project Local cannot weaken Pack contracts")
+        return self
+
+
+class LocalManifest(StrictModel):
+    local_id: str
+    version: str
+    type: Literal["project_local"]
+    requires: LocalRequires
+    mounts: LocalMounts
+    merge_policy: LocalMergePolicy
+    metadata: dict[str, Any] | None = None
+    default_skill: str | None = None
+
+    @field_validator("local_id", "version")
+    @classmethod
+    def _validate_non_empty(cls, value: str) -> str:
+        return validate_non_empty(value, "value")
+
+    @model_validator(mode="after")
+    def _validate_unique_local_xids(self) -> "LocalManifest":
+        assets = self.mounts.knowledge + self.mounts.templates + self.mounts.schemas + self.mounts.review_axes
+        xids = [asset.xid for asset in assets]
+        if len(xids) != len(set(xids)):
+            raise ValueError("LocalManifest contains duplicate local XIDs")
+        return self
+
+
+class ExtendsRef(StrictModel):
+    ref: str
+    xid: str
+    version: str
+    mode: Literal["contract_inheritance"]
+
+    @field_validator("ref", "version")
+    @classmethod
+    def _validate_non_empty(cls, value: str) -> str:
+        return validate_non_empty(value, "value")
+
+    @field_validator("xid")
+    @classmethod
+    def _validate_xid(cls, value: str) -> str:
+        return validate_xid(value)
+
+
+class UsesRef(StrictModel):
+    ref: str
+    version: str
+    mode: Literal["supporting_skill"]
+
+    @field_validator("ref", "version")
+    @classmethod
+    def _validate_non_empty(cls, value: str) -> str:
+        return validate_non_empty(value, "value")
+
+
+class IncludeRef(StrictModel):
+    xid: str
+
+    @field_validator("xid")
+    @classmethod
+    def _validate_xid(cls, value: str) -> str:
+        return validate_xid(value)
+
+
+class InjectsSpec(StrictModel):
+    knowledge: list[str] = Field(default_factory=list)
+
+    @field_validator("knowledge")
+    @classmethod
+    def _validate_knowledge_xids(cls, values: list[str]) -> list[str]:
+        return [validate_xid(value) for value in values]
+
+
+class OutputSpec(StrictModel):
+    template_xid: str | None = None
+    schema_xid: str | None = None
+
+    @field_validator("template_xid", "schema_xid")
+    @classmethod
+    def _validate_optional_xid(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return validate_xid(value)
+
+
+class LocalSkillBinding(StrictModel):
+    extends: list[ExtendsRef]
+    includes: list[IncludeRef] = Field(default_factory=list)
+    uses: list[UsesRef] = Field(default_factory=list)
+    injects: InjectsSpec | None = None
+    output: OutputSpec | None = None
+    review_axes: list[str] = Field(default_factory=list)
+    required_outputs: list[str] = Field(default_factory=list)
+
+    @field_validator("extends")
+    @classmethod
+    def _validate_single_inheritance(cls, values: list[ExtendsRef]) -> list[ExtendsRef]:
+        if len(values) != 1:
+            raise ValueError("MVP supports exactly one extends entry")
+        return values
+
+    @field_validator("review_axes")
+    @classmethod
+    def _validate_review_axes(cls, values: list[str]) -> list[str]:
+        return [validate_xid(value) for value in values]
+
+    @field_validator("required_outputs")
+    @classmethod
+    def _validate_required_outputs(cls, values: list[str]) -> list[str]:
+        return [validate_non_empty(value, "required_output") for value in values]
+
+
+class LocalDomainSkill(StrictModel):
+    skill_id: str
+    xid: str
+    type: Literal["domain_skill_wrapper"]
+    xrefkit: LocalSkillBinding
+
+    @field_validator("skill_id")
+    @classmethod
+    def _validate_skill_id(cls, value: str) -> str:
+        return validate_non_empty(value, "skill_id")
+
+    @field_validator("xid")
+    @classmethod
+    def _validate_xid(cls, value: str) -> str:
+        return validate_xid(value)

xrefkit/models/package_manifest.py

@@ -0,0 +1,126 @@
+"""Pydantic model for package_manifest.yaml."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import Field, field_validator, model_validator
+
+from .common import StrictModel, validate_non_empty, validate_package_id, validate_xid
+
+
+class PackageRequires(StrictModel):
+    xrefkit_core: str
+
+    @field_validator("xrefkit_core")
+    @classmethod
+    def _validate_constraint(cls, value: str) -> str:
+        return validate_non_empty(value, "xrefkit_core")
+
+
+class ProvidedAsset(StrictModel):
+    id: str
+    xid: str
+    path: str
+
+    @field_validator("id", "path")
+    @classmethod
+    def _validate_non_empty(cls, value: str) -> str:
+        return validate_non_empty(value, "value")
+
+    @field_validator("xid")
+    @classmethod
+    def _validate_xid(cls, value: str) -> str:
+        return validate_xid(value)
+
+
+class ProvidedSkill(ProvidedAsset):
+    contract_role: str | None = None
+    required_outputs: list[str] = Field(default_factory=list)
+    required_knowledge: list[str] = Field(default_factory=list)
+    required_review_axes: list[str] = Field(default_factory=list)
+    must_not: list[str] = Field(default_factory=list)
+
+    @field_validator("required_outputs", "required_knowledge", "required_review_axes", "must_not")
+    @classmethod
+    def _validate_string_list(cls, values: list[str]) -> list[str]:
+        return [validate_non_empty(value, "list item") for value in values]
+
+
+class PackageProvides(StrictModel):
+    skills: list[ProvidedSkill]
+    fragments: list[ProvidedAsset] = Field(default_factory=list)
+    knowledge: list[ProvidedAsset] = Field(default_factory=list)
+    review_axes: list[ProvidedAsset] = Field(default_factory=list)
+    schemas: list[ProvidedAsset] = Field(default_factory=list)
+    templates: list[ProvidedAsset] = Field(default_factory=list)
+
+    @field_validator("skills")
+    @classmethod
+    def _require_skills(cls, values: list[ProvidedSkill]) -> list[ProvidedSkill]:
+        if not values:
+            raise ValueError("provides.skills must not be empty")
+        return values
+
+    @model_validator(mode="after")
+    def _validate_asset_ids(self) -> "PackageProvides":
+        for name in ("skills", "fragments", "knowledge", "review_axes", "schemas", "templates"):
+            assets = getattr(self, name)
+            ids = [asset.id for asset in assets]
+            if len(ids) != len(set(ids)):
+                raise ValueError(f"provides.{name} contains duplicate ids")
+        return self
+
+
+class PackageContract(StrictModel):
+    can_be_extended_by_local_skill: bool = True
+    local_skill_can_weaken_contract: bool = False
+    local_can_weaken_required_outputs: bool = False
+    local_can_override_must_not: bool = False
+    requires_unknown_declaration: bool = True
+    requires_traceability: bool = True
+
+    @model_validator(mode="after")
+    def _enforce_mvp_policy(self) -> "PackageContract":
+        if self.local_skill_can_weaken_contract:
+            raise ValueError("MVP does not allow local skills to weaken package contracts")
+        if self.local_can_weaken_required_outputs:
+            raise ValueError("MVP does not allow local skills to weaken required outputs")
+        if self.local_can_override_must_not:
+            raise ValueError("MVP does not allow local skills to override must_not")
+        return self
+
+
+class PackageManifest(StrictModel):
+    package_id: str
+    package_type: Literal["skill_package"]
+    version: str
+    requires: PackageRequires
+    provides: PackageProvides
+    contract: PackageContract
+    metadata: dict[str, Any] | None = None
+
+    @field_validator("package_id")
+    @classmethod
+    def _validate_package_id(cls, value: str) -> str:
+        return validate_package_id(value)
+
+    @field_validator("version")
+    @classmethod
+    def _validate_version(cls, value: str) -> str:
+        return validate_non_empty(value, "version")
+
+    @model_validator(mode="after")
+    def _validate_unique_xids(self) -> "PackageManifest":
+        assets = (
+            self.provides.skills
+            + self.provides.fragments
+            + self.provides.knowledge
+            + self.provides.review_axes
+            + self.provides.schemas
+            + self.provides.templates
+        )
+        xids = [asset.xid for asset in assets]
+        if len(xids) != len(set(xids)):
+            raise ValueError("package manifest contains duplicate XIDs")
+        return self

xrefkit/models/run_log.py

@@ -0,0 +1,276 @@
+"""Pydantic models for canonical JSONL run log events."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Literal, Union
+
+from pydantic import Field, field_validator, model_validator
+
+from .common import SourceTraceEntry, StrictModel, XidLoadedRef, validate_content_hash, validate_non_empty, validate_xid
+
+
+class Requester(StrictModel):
+    type: Literal["client_ip", "user_id"]
+    client_ip: str | None = None
+    user_id: str | None = None
+    identity_assurance: str
+
+    @field_validator("identity_assurance")
+    @classmethod
+    def _validate_identity_assurance(cls, value: str) -> str:
+        return validate_non_empty(value, "identity_assurance")
+
+    @model_validator(mode="after")
+    def _validate_identity(self) -> "Requester":
+        if self.type == "client_ip" and not self.client_ip:
+            raise ValueError("requester.client_ip is required when requester.type='client_ip'")
+        if self.type == "user_id" and not self.user_id:
+            raise ValueError("requester.user_id is required when requester.type='user_id'")
+        return self
+
+
+class Actor(StrictModel):
+    type: str
+    client_name: str | None = None
+    session_id: str | None = None
+
+    @field_validator("type")
+    @classmethod
+    def _validate_type(cls, value: str) -> str:
+        return validate_non_empty(value, "type")
+
+
+class RunRequest(StrictModel):
+    operation: str
+    skill_id: str | None = None
+
+    @field_validator("operation")
+    @classmethod
+    def _validate_operation(cls, value: str) -> str:
+        return validate_non_empty(value, "operation")
+
+
+class RunLogEventBase(StrictModel):
+    run_id: str
+    event_type: str
+    timestamp: datetime
+
+    @field_validator("run_id")
+    @classmethod
+    def _validate_run_id(cls, value: str) -> str:
+        return validate_non_empty(value, "run_id")
+
+
+class RunStartEvent(RunLogEventBase):
+    event_type: Literal["run.start"]
+    requester: Requester
+    actor: Actor | None = None
+    request: RunRequest
+
+
+class ContextResolvedEvent(RunLogEventBase):
+    event_type: Literal["context.resolved"]
+    effective_skill_id: str
+    resolution_mode: Literal["entry", "branch", "full"]
+    source_trace: list[SourceTraceEntry]
+    bundle_hash: str | None = None
+
+    @field_validator("effective_skill_id")
+    @classmethod
+    def _validate_effective_skill_id(cls, value: str) -> str:
+        return validate_non_empty(value, "effective_skill_id")
+
+    @field_validator("bundle_hash")
+    @classmethod
+    def _validate_bundle_hash(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return validate_content_hash(value)
+
+
+class XidsReferencedEvent(RunLogEventBase):
+    event_type: Literal["xids.referenced"]
+    referenced_xids: list[str]
+
+    @field_validator("referenced_xids")
+    @classmethod
+    def _validate_xids(cls, values: list[str]) -> list[str]:
+        return [validate_xid(value) for value in values]
+
+
+class XidsLoadedEvent(RunLogEventBase):
+    event_type: Literal["xids.loaded"]
+    loaded_xids: list[XidLoadedRef]
+
+
+class XidsUsedEvent(RunLogEventBase):
+    event_type: Literal["xids.used"]
+    used_xids: list[str]
+
+    @field_validator("used_xids")
+    @classmethod
+    def _validate_xids(cls, values: list[str]) -> list[str]:
+        return [validate_xid(value) for value in values]
+
+
+class UnknownsReportedEvent(RunLogEventBase):
+    event_type: Literal["unknowns.reported"]
+    unknowns: list[str]
+
+    @field_validator("unknowns")
+    @classmethod
+    def _validate_unknowns(cls, values: list[str]) -> list[str]:
+        return [validate_non_empty(value, "unknown") for value in values]
+
+
+class AssumptionsReportedEvent(RunLogEventBase):
+    event_type: Literal["assumptions.reported"]
+    assumptions: list[str]
+
+    @field_validator("assumptions")
+    @classmethod
+    def _validate_assumptions(cls, values: list[str]) -> list[str]:
+        return [validate_non_empty(value, "assumption") for value in values]
+
+
+class BranchLoadedEvent(RunLogEventBase):
+    event_type: Literal["branch.loaded"]
+    branch_xid: str
+    loaded_xids: list[XidLoadedRef] = Field(default_factory=list)
+
+    @field_validator("branch_xid")
+    @classmethod
+    def _validate_branch_xid(cls, value: str) -> str:
+        return validate_xid(value)
+
+
+class ConflictDetectedEvent(RunLogEventBase):
+    event_type: Literal["conflict.detected"]
+    severity: Literal["error", "warning", "info"]
+    code: str
+    message: str
+    xids: list[str] = Field(default_factory=list)
+
+    @field_validator("code", "message")
+    @classmethod
+    def _validate_non_empty(cls, value: str) -> str:
+        return validate_non_empty(value, "value")
+
+    @field_validator("xids")
+    @classmethod
+    def _validate_xids(cls, values: list[str]) -> list[str]:
+        return [validate_xid(value) for value in values]
+
+
+class RunResult(StrictModel):
+    status: Literal["completed", "completed_with_unknowns", "failed", "blocked"]
+    contract_passed: bool
+    required_outputs_present: bool | None = None
+    unknowns_count: int | None = None
+    assumptions_count: int | None = None
+    message: str | None = None
+
+    @field_validator("unknowns_count", "assumptions_count")
+    @classmethod
+    def _validate_counts(cls, value: int | None) -> int | None:
+        if value is not None and value < 0:
+            raise ValueError("counts must be zero or greater")
+        return value
+
+
+class RunCompleteEvent(RunLogEventBase):
+    event_type: Literal["run.complete"]
+    result: RunResult
+
+
+RunLogEvent = Annotated[
+    Union[
+        RunStartEvent,
+        ContextResolvedEvent,
+        XidsReferencedEvent,
+        XidsLoadedEvent,
+        XidsUsedEvent,
+        UnknownsReportedEvent,
+        AssumptionsReportedEvent,
+        BranchLoadedEvent,
+        ConflictDetectedEvent,
+        RunCompleteEvent,
+    ],
+    Field(discriminator="event_type"),
+]
+
+
+class RunLogAggregate(StrictModel):
+    run_id: str
+    events: list[RunLogEvent]
+
+    @field_validator("run_id")
+    @classmethod
+    def _validate_run_id(cls, value: str) -> str:
+        return validate_non_empty(value, "run_id")
+
+    @field_validator("events")
+    @classmethod
+    def _validate_events_not_empty(cls, values: list[RunLogEvent]) -> list[RunLogEvent]:
+        if not values:
+            raise ValueError("events must not be empty")
+        return values
+
+    @model_validator(mode="after")
+    def _validate_run_consistency(self) -> "RunLogAggregate":
+        for event in self.events:
+            if event.run_id != self.run_id:
+                raise ValueError("all run log events must share the aggregate run_id")
+
+        if not any(isinstance(event, RunStartEvent) for event in self.events):
+            raise ValueError("run.start event is required")
+
+        complete_count = sum(1 for event in self.events if isinstance(event, RunCompleteEvent))
+        if complete_count > 1:
+            raise ValueError("run.complete may appear at most once")
+
+        timestamps = [event.timestamp for event in self.events]
+        if timestamps != sorted(timestamps):
+            raise ValueError("run log events must be ordered by timestamp")
+
+        loaded_xids: set[str] = set()
+        used_xids: set[str] = set()
+        for event in self.events:
+            if isinstance(event, XidsLoadedEvent):
+                loaded_xids.update(item.xid for item in event.loaded_xids)
+            elif isinstance(event, BranchLoadedEvent):
+                loaded_xids.update(item.xid for item in event.loaded_xids)
+            elif isinstance(event, XidsUsedEvent):
+                used_xids.update(event.used_xids)
+
+        missing = sorted(used_xids - loaded_xids)
+        if missing:
+            raise ValueError(f"used_xids must be a subset of loaded_xids; missing: {missing}")
+        return self
+
+    @property
+    def referenced_xids(self) -> set[str]:
+        values: set[str] = set()
+        for event in self.events:
+            if isinstance(event, XidsReferencedEvent):
+                values.update(event.referenced_xids)
+        return values
+
+    @property
+    def loaded_xids(self) -> set[str]:
+        values: set[str] = set()
+        for event in self.events:
+            if isinstance(event, XidsLoadedEvent):
+                values.update(item.xid for item in event.loaded_xids)
+            elif isinstance(event, BranchLoadedEvent):
+                values.update(item.xid for item in event.loaded_xids)
+        return values
+
+    @property
+    def used_xids(self) -> set[str]:
+        values: set[str] = set()
+        for event in self.events:
+            if isinstance(event, XidsUsedEvent):
+                values.update(event.used_xids)
+        return values