plm-skill-kernel 1.0.2__tar.gz → 1.1.0__tar.gz

{plm_skill_kernel-1.0.2 → plm_skill_kernel-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plm-skill-kernel
-Version: 1.0.2
+Version: 1.1.0
 Summary: TracePulse PLM Skill Kernel — Wave 2 Conv A. Decorator-based Skill SDK + V1 in-process dispatcher + Kernel HTTP server stub matching CR.10 §7.bis (POST /v1/skills/{id}/invoke). Ships 3 starter skills (cleansing.normalise, cleansing.dedupe, bpmn.generate). Sibling of plm-engine-core; the two communicate over the V1.1 HTTP loopback (SKILL_KERNEL_LOOPBACK=on) — no Python-level coupling at the dispatch boundary.
 Author: TracePulse
 License: Proprietary
@@ -17,6 +17,8 @@ Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
 Requires-Dist: httpx<1,>=0.27; extra == "test"
+Provides-Extra: conformance
+Requires-Dist: plm-skill-packages; extra == "conformance"
 Provides-Extra: docs
 Requires-Dist: pdoc>=14.0; extra == "docs"
 

{plm_skill_kernel-1.0.2 → plm_skill_kernel-1.1.0}/plm_skill_kernel/__init__.py

@@ -14,7 +14,7 @@ sanctioned interaction is the V1.1 HTTP loopback (env-flagged on
 ``SKILL_KERNEL_LOOPBACK``); any Python-level reach-in is forbidden by
 the import-linter contract in ``pyproject.toml``.
 """
-__version__ = "1.0.2"
+__version__ = "1.1.0"
 
 # The decorator + sdk surface is the public authoring API. Re-exported
 # here so callers write ``from plm_skill_kernel import skill`` rather

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/__init__.py

@@ -0,0 +1,84 @@
+"""Conformance contract layer (FTR-2008 / MV1-DEC-018 Candidate 1).
+
+Owns:
+- :class:`ManifestProfileValidator` typing.Protocol (the validator seam)
+- :class:`ConformanceReport` + :class:`ConformanceFinding` (report models)
+- :data:`REPORT_CONTRACT_VERSION` (independent SemVer per MV1-DEC-005)
+- :class:`ExitCode` constants (MV1-DEC-006)
+
+Does NOT extend or import the 4 frozen SDK wire models
+(SkillContext, SkillInvokeRequest, SkillInvokeResult, SkillErrorEnvelope).
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Type
+
+from ._version import REPORT_CONTRACT_VERSION
+from .exit_codes import ExitCode
+from .models import (
+    ConformanceFinding,
+    ConformanceReport,
+    EnumerationEntry,
+    EnumerationPayload,
+    EnumerationState,
+    ExecutionStatusCounts,
+    FindingExecutionStatus,
+    FindingSeverity,
+    ResolvedReference,
+    SeverityCounts,
+    Verdict,
+)
+from .protocol import ManifestProfileValidator
+from ._verdict import derive_exit_code, expected_exit_code
+
+__all__ = [
+    "REPORT_CONTRACT_VERSION",
+    "ConformanceFinding",
+    "ConformanceReport",
+    "EnumerationEntry",
+    "EnumerationPayload",
+    "EnumerationState",
+    "ExitCode",
+    "ExecutionStatusCounts",
+    "FindingExecutionStatus",
+    "FindingSeverity",
+    "ManifestProfileValidator",
+    "ResolvedReference",
+    "SeverityCounts",
+    "Verdict",
+    "available_profiles",
+    "derive_exit_code",
+    "expected_exit_code",
+    "get_validator",
+    "register_profile",
+]
+
+
+# ── Profile registration seam ────────────────────────────────────────────────
+
+_PROFILE_REGISTRY: Dict[str, Type[ManifestProfileValidator]] = {}
+
+
+def register_profile(
+    profile_id: str, validator_cls: Type[ManifestProfileValidator]
+) -> None:
+    """Register a validator class for a profile ID.
+
+    Called by profile implementations (e.g. in plm-skill-packages) at
+    import time to make themselves available to the CLI.
+    """
+    _PROFILE_REGISTRY[profile_id] = validator_cls
+
+
+def get_validator(profile_id: str) -> ManifestProfileValidator:
+    """Instantiate and return the validator for *profile_id*.
+
+    Raises :class:`KeyError` if *profile_id* is not registered.
+    """
+    cls = _PROFILE_REGISTRY[profile_id]
+    return cls()
+
+
+def available_profiles() -> List[str]:
+    """Return list of registered profile IDs."""
+    return sorted(_PROFILE_REGISTRY.keys())

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/_cli.py

@@ -0,0 +1,143 @@
+"""CLI entry for ``plm-skill-conformance`` — conformance validation runner.
+
+Usage::
+
+    plm-skill-conformance --profile manifest-v1 [--report <path>] [snapshot_root]
+
+Exit codes per MV1-DEC-006:
+    0  = VALID
+    1  = INVALID (blocking findings)
+    2  = decision-gated / not-executable / degraded
+    64 = invoker-correctable (usage/config/profile/unsafe-path)
+    70 = unexpected defect
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from ._output_safety import validate_output_path
+from ._serialize import serialize_report
+from ._terminal import render_terminal
+from .exit_codes import ExitCode
+from .models import ConformanceReport
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    """Console-script entry — ``plm-skill-conformance``.
+
+    Separate from the server CLI (``plm-skill-kernel``) to satisfy AC10:
+    running without --profile on the server CLI remains unchanged.
+    """
+    parser = argparse.ArgumentParser(
+        prog="plm-skill-conformance",
+        description="Run manifest conformance validation against a profile.",
+    )
+    parser.add_argument(
+        "--profile",
+        required=False,
+        default=None,
+        help="Profile to validate against (e.g. 'manifest-v1'). Required.",
+    )
+    parser.add_argument(
+        "--report",
+        type=str,
+        default=None,
+        help=(
+            "Output path for the JSON report. "
+            "Default: <snapshot_root>/.plm/skill-conformance/report.json"
+        ),
+    )
+    parser.add_argument(
+        "snapshot_root",
+        nargs="?",
+        default=".",
+        help="Path to the package snapshot root (default: current directory).",
+    )
+
+    args = parser.parse_args(argv)
+
+    # MV1-DEC-006: missing --profile is invoker-correctable (exit 64)
+    if args.profile is None:
+        print("ERROR: --profile is required.", file=sys.stderr)
+        sys.exit(ExitCode.INVOKER_CORRECTABLE)
+
+    # Resolve snapshot root
+    snapshot_root = Path(args.snapshot_root).resolve()
+
+    # Determine report output path
+    if args.report:
+        report_path = Path(args.report).resolve()
+    else:
+        report_path = snapshot_root / ".plm" / "skill-conformance" / "report.json"
+
+    # Output-path safety check (AC7, AC8, AC14) — BEFORE any validation
+    safety_error = validate_output_path(report_path, snapshot_root)
+    if safety_error:
+        print(f"ERROR: {safety_error}", file=sys.stderr)
+        sys.exit(ExitCode.INVOKER_CORRECTABLE)
+
+    # Load the profile validator via registration seam
+    try:
+        from . import available_profiles, get_validator
+
+        validator = get_validator(args.profile)
+    except KeyError:
+        from . import available_profiles
+
+        print(
+            f"ERROR: Unknown profile '{args.profile}'. "
+            f"Available: {available_profiles()}",
+            file=sys.stderr,
+        )
+        sys.exit(ExitCode.INVOKER_CORRECTABLE)
+    except ImportError as exc:
+        print(
+            f"ERROR: Failed to load profile validator: {exc}. "
+            f"Install plm-skill-packages or the appropriate validator package.",
+            file=sys.stderr,
+        )
+        sys.exit(ExitCode.INVOKER_CORRECTABLE)
+    except Exception as exc:
+        print(
+            f"ERROR: Failed to instantiate profile validator: {exc}",
+            file=sys.stderr,
+        )
+        sys.exit(ExitCode.INVOKER_CORRECTABLE)
+
+    # Run validation — fail-closed: exceptions → exit 70
+    try:
+        report = validator.validate(str(snapshot_root))
+    except Exception as exc:
+        print(
+            f"DEFECT: Validator raised unexpected error: {type(exc).__name__}: {exc}",
+            file=sys.stderr,
+        )
+        sys.exit(ExitCode.DEFECT)
+
+    # Canonicalize for byte-identity (AC8/AC13)
+    canonical_report = ConformanceReport.canonicalize(report)
+
+    # Write JSON report — fail-closed: exceptions → exit 70
+    try:
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report_path.write_text(
+            serialize_report(canonical_report), encoding="utf-8"
+        )
+    except Exception as exc:
+        print(
+            f"DEFECT: Failed to write report to '{report_path}': {exc}",
+            file=sys.stderr,
+        )
+        sys.exit(ExitCode.DEFECT)
+
+    # Terminal projection
+    render_terminal(canonical_report)
+
+    # Exit with the guaranteed-consistent exit code from the report
+    sys.exit(canonical_report.exit_code)
+
+
+__all__ = ["main"]

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/_output_safety.py

@@ -0,0 +1,55 @@
+"""Output-path safety validation (AC7/AC8/AC14).
+
+Rules:
+- Report path OUTSIDE snapshot root → always safe.
+- Report path INSIDE snapshot root under a pre-excluded directory → safe.
+- Report path INSIDE snapshot root, NOT under a pre-excluded directory →
+  FAIL before writing (exit 64, invoker-correctable).
+
+The default report destination is ``<snapshot_root>/.plm/skill-conformance/report.json``
+which is inside the snapshot but under ``.plm/`` (pre-excluded), so it is safe.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+# Directories that are pre-excluded from package enumeration — safe to write into.
+PRE_EXCLUDED_DIRS = frozenset({
+    ".plm", ".git", ".federation", "__pycache__", "node_modules",
+    ".venv", "venv", ".tox", ".mypy_cache", ".pytest_cache",
+})
+
+
+def validate_output_path(report_path: Path, snapshot_root: Path) -> Optional[str]:
+    """Return an error message if *report_path* is unsafe; ``None`` if OK.
+
+    An unsafe path is one that is inside the snapshot root but not under
+    a pre-excluded directory — writing there would contaminate the
+    authoring snapshot and potentially alter enumeration results.
+    """
+    # Resolve both to absolute for reliable comparison
+    report_abs = report_path.resolve()
+    snapshot_abs = snapshot_root.resolve()
+
+    # Outside snapshot → always safe
+    try:
+        relative = report_abs.relative_to(snapshot_abs)
+    except ValueError:
+        return None
+
+    # Inside snapshot — check if first path component is pre-excluded
+    parts = relative.parts
+    if parts and parts[0] in PRE_EXCLUDED_DIRS:
+        return None
+
+    return (
+        f"Report path '{report_abs}' is inside the snapshot root "
+        f"'{snapshot_abs}' and not under a pre-excluded directory "
+        f"({sorted(PRE_EXCLUDED_DIRS)}). Writing here would contaminate "
+        f"the snapshot. Use --report with a path outside the snapshot "
+        f"or under .plm/."
+    )
+
+
+__all__ = ["PRE_EXCLUDED_DIRS", "validate_output_path"]

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/_serialize.py

@@ -0,0 +1,45 @@
+"""Canonical report serialization (AC8/AC13 byte-identity guarantee).
+
+This module is the SINGLE serialization boundary for conformance reports.
+All code that produces report JSON bytes MUST use :func:`serialize_report`
+rather than calling ``model_dump_json()`` directly.
+
+Key guarantee: ``ensure_ascii=True`` ensures non-ASCII characters are
+escaped as ``\\uXXXX``, making the output byte-identical across platforms
+regardless of locale or filesystem encoding.
+
+Added in REPORT_CONTRACT_VERSION 1.1.0 (MV1-DEC-005 SemVer-minor).
+"""
+from __future__ import annotations
+
+import json
+
+from .models import ConformanceReport
+
+
+def serialize_report(report: ConformanceReport) -> str:
+    """Produce canonical JSON for a conformance report.
+
+    Round-trips through Pydantic's serializer (for type coercion and
+    field-order stability) then re-serializes with ``ensure_ascii=True``
+    for cross-platform byte-identity.
+
+    Parameters
+    ----------
+    report : ConformanceReport
+        Should already be canonicalized via ``ConformanceReport.canonicalize()``.
+
+    Returns
+    -------
+    str
+        Canonical JSON string (indent=2, ensure_ascii=True, no trailing newline).
+    """
+    return json.dumps(
+        json.loads(report.model_dump_json()),
+        indent=2,
+        ensure_ascii=True,
+        sort_keys=False,
+    )
+
+
+__all__ = ["serialize_report"]

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/_terminal.py

@@ -0,0 +1,70 @@
+"""Deterministic terminal projection (MV1-DEC-005).
+
+Order: verdict line → profile/version → report contract version → counts →
+findings sorted by (severity DESC [error>warning>info], rule_code ASC, path ASC).
+
+Same report → identical terminal output.
+"""
+from __future__ import annotations
+
+import sys
+from typing import IO
+
+from .models import (
+    ConformanceFinding,
+    ConformanceReport,
+    FindingSeverity,
+)
+
+
+_SEVERITY_ORDER = {
+    FindingSeverity.ERROR: 0,
+    FindingSeverity.WARNING: 1,
+    FindingSeverity.INFO: 2,
+}
+
+
+def render_terminal(report: ConformanceReport, *, stream: IO[str] = sys.stdout) -> None:
+    """Render the conformance report to terminal in deterministic order.
+
+    Parameters
+    ----------
+    report : ConformanceReport
+        The canonicalized report to render.
+    stream : IO[str]
+        Output stream (default: stdout). Overridable for testing.
+    """
+    # Verdict line
+    stream.write(f"\nVerdict: {report.verdict.value}\n")
+    stream.write(f"Profile: {report.profile_id} ({report.profile_version})\n")
+    stream.write(f"Report contract: {report.report_contract_version}\n")
+
+    # Counts
+    c = report.counts_by_severity
+    stream.write(
+        f"\nFindings: {c.error} error, {c.warning} warning, {c.info} info\n"
+    )
+
+    # Deterministically ordered findings
+    if report.findings:
+        ordered = sorted(
+            report.findings,
+            key=lambda f: (
+                _SEVERITY_ORDER.get(f.severity, 99),
+                f.rule_code,
+                f.path or "",
+            ),
+        )
+        stream.write("\n--- Findings ---\n")
+        for f in ordered:
+            path_str = f" @ {f.path}" if f.path else ""
+            decision_str = f" [decision: {f.decision_id}]" if f.decision_id else ""
+            stream.write(
+                f"  [{f.severity.value.upper()}] "
+                f"{f.rule_code}{path_str}: {f.message}{decision_str}\n"
+            )
+
+    stream.write("\n")
+
+
+__all__ = ["render_terminal"]

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/_verdict.py

@@ -0,0 +1,74 @@
+"""Verdict-to-exit-code derivation (MV1-DEC-006).
+
+Deterministic verdict precedence (highest → lowest):
+
+1. INVALID (exit 1) — any finding with severity=error + execution_status=invalid
+2. decision-gated (exit 2) — any finding with execution_status=blocked_by_decision
+3. required-not-executable (exit 2) — execution_status=not_executable
+4. compatibility-not-executable (exit 2) — execution_status=compatibility_not_executable
+5. degraded-enumeration (exit 2) — enumeration.state == DEGRADED
+6. VALID (exit 0) — none of the above
+
+When INVALID and gated/not-executable co-exist, INVALID wins (exit 1 > exit 2).
+Rationale: blocking conformance failures are author-actionable NOW (the author
+can fix the schema error); gated states depend on external resolution (a decision
+owner must close the decision, or a dependency must be published). Reporting
+INVALID is the conservative/safe outcome — it surfaces the actionable fix first.
+
+The precedence is enforced by the *validator* when it produces the verdict.
+The kernel-side ``derive_exit_code`` simply maps verdict → exit code and
+returns 70 (defect) for any unknown/future verdict value (fail-closed).
+
+PENDING RATIFICATION (FTR-2034 decision register)
+──────────────────────────────────────────────────
+This verdict-precedence rule (INVALID > gated when both coexist) is a proposed
+kernel-side consistency rule. It is NOT yet a ratified MV1-DEC-* decision.
+It is locked by regression tests in tests/conformance/test_verdict_derivation.py
+(test_invalid_wins_over_gated, test_precedence_invalid_over_not_executable).
+Any change to this ordering requires explicit owner ratification via FTR-2034.
+"""
+from __future__ import annotations
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .exit_codes import ExitCode
+from .models import Verdict
+
+if TYPE_CHECKING:
+    from .models import ConformanceReport
+
+
+_VERDICT_TO_EXIT: dict[Verdict, int] = {
+    Verdict.VALID: ExitCode.VALID,
+    Verdict.INVALID: ExitCode.INVALID,
+    Verdict.DECISION_GATED: ExitCode.GATED,
+    Verdict.REQUIRED_NOT_EXECUTABLE: ExitCode.GATED,
+    Verdict.COMPATIBILITY_NOT_EXECUTABLE: ExitCode.GATED,
+    Verdict.DEGRADED_ENUMERATION: ExitCode.GATED,
+}
+
+
+def expected_exit_code(verdict: Verdict) -> int:
+    """Single authority for verdict → exit-code mapping (MV1-DEC-006).
+
+    Pure function: takes only a Verdict enum, never reads report.exit_code.
+    Used by the model validator to enforce consistency and by all report
+    producers to compute the correct exit_code before construction.
+
+    Fail-closed: unknown verdict value returns 70 (defect).
+    """
+    return _VERDICT_TO_EXIT.get(verdict, ExitCode.DEFECT)
+
+
+def derive_exit_code(report: "ConformanceReport") -> int:
+    """Map report verdict to exit code — thin wrapper over expected_exit_code.
+
+    Kept for backward compatibility. Delegates entirely to
+    :func:`expected_exit_code`.
+    """
+    return expected_exit_code(report.verdict)
+
+
+__all__ = ["derive_exit_code", "expected_exit_code"]

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/_version.py

@@ -0,0 +1,7 @@
+"""Report contract version — independently versioned per MV1-DEC-005.
+
+SemVer rules:
+- Minor bump: add optional field to ConformanceReport or ConformanceFinding.
+- Major bump: remove/rename/require a field, or change verdict semantics.
+"""
+REPORT_CONTRACT_VERSION = "1.1.0"

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/exit_codes.py

@@ -0,0 +1,23 @@
+"""Exit-code constants per MV1-DEC-006.
+
+Mapping:
+    0  — VALID (conformant)
+    1  — INVALID (blocking conformance findings, severity=error)
+    2  — decision-gated / required-not-executable /
+         compatibility-not-executable / degraded-enumeration
+    64 — invoker-correctable (usage, config, profile selection, unsafe path)
+    70 — unexpected defect (validator crash, serialization failure, write error)
+"""
+
+
+class ExitCode:
+    """MV1-DEC-006 exit codes for conformance validation."""
+
+    VALID = 0
+    INVALID = 1
+    GATED = 2
+    INVOKER_CORRECTABLE = 64
+    DEFECT = 70
+
+
+__all__ = ["ExitCode"]

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/models.py

@@ -0,0 +1,301 @@
+"""Conformance report and finding models (MV1-DEC-005 / MV1-DEC-018).
+
+All models are frozen Pydantic v2 with ``extra="forbid"`` — the same
+pattern used by the SDK wire shapes, but these live in a separate
+namespace and are independently versioned by ``REPORT_CONTRACT_VERSION``.
+
+The ``ConformanceReport`` carries a ``model_validator`` that enforces
+the AC9 fail-closed invariant: verdict=VALID is rejected if the report
+contains blocking findings, decision-gated / not-executable states, or
+degraded enumeration.
+"""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ._version import REPORT_CONTRACT_VERSION
+
+
+# ── Enumerations ─────────────────────────────────────────────────────────────
+
+
+class Verdict(str, Enum):
+    """Overall conformance verdict."""
+
+    VALID = "VALID"
+    INVALID = "INVALID"
+    DECISION_GATED = "decision-gated"
+    REQUIRED_NOT_EXECUTABLE = "required-not-executable"
+    COMPATIBILITY_NOT_EXECUTABLE = "compatibility-not-executable"
+    DEGRADED_ENUMERATION = "degraded-enumeration"
+
+
+class FindingSeverity(str, Enum):
+    """Finding severity level."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class FindingExecutionStatus(str, Enum):
+    """Per-finding execution status."""
+
+    VALID = "valid"
+    INVALID = "invalid"
+    BLOCKED_BY_DECISION = "blocked_by_decision"
+    COMPATIBILITY_NOT_EXECUTABLE = "compatibility_not_executable"
+    NOT_EXECUTABLE = "not_executable"
+
+
+class EnumerationState(str, Enum):
+    """Enumeration completeness state."""
+
+    COMPLETE = "complete"
+    DEGRADED = "degraded"
+
+
+# ── Finding model ────────────────────────────────────────────────────────────
+
+
+class ConformanceFinding(BaseModel):
+    """Single conformance finding — immutable, deterministically serializable."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    rule_code: str = Field(min_length=1)
+    severity: FindingSeverity
+    path: Optional[str] = None
+    message: str = Field(min_length=1)
+    remediation: Optional[str] = None
+    decision_id: Optional[str] = None
+    execution_status: FindingExecutionStatus
+
+
+# ── Enumeration models ───────────────────────────────────────────────────────
+
+
+class EnumerationEntry(BaseModel):
+    """Single entry in the enumeration payload."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    relative_path: str
+    ordering_key: str
+    entry_state: str
+    reference_state: Optional[str] = None
+
+
+class EnumerationPayload(BaseModel):
+    """Enumeration section of the conformance report."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    state: EnumerationState
+    causes: List[str] = Field(default_factory=list)
+    entries: List[EnumerationEntry] = Field(default_factory=list)
+
+
+# ── Reference inventory ──────────────────────────────────────────────────────
+
+
+class ResolvedReference(BaseModel):
+    """Single entry in the resolved-reference inventory."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    reference_id: str
+    resolved_path: Optional[str] = None
+    status: str
+
+
+# ── Count models ─────────────────────────────────────────────────────────────
+
+
+class SeverityCounts(BaseModel):
+    """Finding counts by severity."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    error: int = 0
+    warning: int = 0
+    info: int = 0
+
+
+class ExecutionStatusCounts(BaseModel):
+    """Finding counts by execution status."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    valid: int = 0
+    invalid: int = 0
+    blocked_by_decision: int = 0
+    compatibility_not_executable: int = 0
+    not_executable: int = 0
+
+
+# ── Top-level report ─────────────────────────────────────────────────────────
+
+
+_SEVERITY_RANK = {
+    FindingSeverity.ERROR: 0,
+    FindingSeverity.WARNING: 1,
+    FindingSeverity.INFO: 2,
+}
+
+# Execution statuses that make VALID impossible (AC9).
+_BLOCKING_EXECUTION_STATUSES = frozenset({
+    FindingExecutionStatus.BLOCKED_BY_DECISION,
+    FindingExecutionStatus.NOT_EXECUTABLE,
+    FindingExecutionStatus.COMPATIBILITY_NOT_EXECUTABLE,
+})
+
+
+class ConformanceReport(BaseModel):
+    """Top-level conformance report — the canonical machine-readable output.
+
+    Versioned by ``report_contract_version`` (SemVer per MV1-DEC-005).
+    Adding optional fields is a minor bump; removing/renaming/requiring
+    a field or changing verdict semantics is a major bump.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    report_contract_version: str = Field(default=REPORT_CONTRACT_VERSION)
+    profile_id: str
+    profile_version: str
+    schema_version: Optional[str] = None
+    rule_versions: Optional[Dict[str, str]] = None
+
+    verdict: Verdict
+    exit_code: int
+
+    findings: List[ConformanceFinding] = Field(default_factory=list)
+    counts_by_severity: SeverityCounts = Field(default_factory=SeverityCounts)
+    counts_by_execution_status: ExecutionStatusCounts = Field(
+        default_factory=ExecutionStatusCounts
+    )
+
+    enumeration: Optional[EnumerationPayload] = None
+    resolved_references: List[ResolvedReference] = Field(default_factory=list)
+    migration_assessment: Optional[Dict[str, Any]] = None
+
+    @model_validator(mode="after")
+    def _ac9_fail_closed_guard(self) -> "ConformanceReport":
+        """Reject VALID verdict when blocking content exists (AC9).
+
+        The Kernel does NOT trust the validator's verdict blindly. If any
+        of these conditions hold, VALID is impossible and construction
+        raises ``ValidationError``.
+        """
+        if self.verdict != Verdict.VALID:
+            return self
+
+        # Check blocking findings (severity=error)
+        has_blocking = any(
+            f.severity == FindingSeverity.ERROR for f in self.findings
+        )
+        if has_blocking:
+            raise ValueError(
+                "verdict=VALID is impossible: report contains error-severity findings"
+            )
+
+        # Check decision-gated / not-executable states
+        has_gated = any(
+            f.execution_status in _BLOCKING_EXECUTION_STATUSES
+            for f in self.findings
+        )
+        if has_gated:
+            raise ValueError(
+                "verdict=VALID is impossible: report contains "
+                "decision-gated or not-executable findings"
+            )
+
+        # Check degraded enumeration
+        if self.enumeration and self.enumeration.state == EnumerationState.DEGRADED:
+            raise ValueError(
+                "verdict=VALID is impossible: enumeration is degraded"
+            )
+
+        return self
+
+    @model_validator(mode="after")
+    def _exit_code_consistency_guard(self) -> "ConformanceReport":
+        """Reject reports where exit_code disagrees with verdict.
+
+        Uses :func:`expected_exit_code` (the single authority) which
+        derives from verdict alone — never reads self.exit_code, so
+        this guard is not a tautology.
+        """
+        from ._verdict import expected_exit_code  # deferred to avoid circular
+
+        expected = expected_exit_code(self.verdict)
+        if self.exit_code != expected:
+            raise ValueError(
+                f"exit_code={self.exit_code} is inconsistent with "
+                f"verdict={self.verdict.value} (expected {expected})"
+            )
+        return self
+
+    @classmethod
+    def canonicalize(cls, report: "ConformanceReport") -> "ConformanceReport":
+        """Return a new instance with all lists in deterministic order.
+
+        Sort keys:
+        - findings: (severity_rank ASC, rule_code ASC, path ASC)
+        - resolved_references: (reference_id ASC)
+        - enumeration.entries: (ordering_key ASC)
+
+        Call before serialization to guarantee byte-identity (AC8/AC13).
+        """
+        sorted_findings = sorted(
+            report.findings,
+            key=lambda f: (
+                _SEVERITY_RANK.get(f.severity, 99),
+                f.rule_code,
+                f.path or "",
+            ),
+        )
+        sorted_refs = sorted(
+            report.resolved_references,
+            key=lambda r: r.reference_id,
+        )
+        sorted_enum = None
+        if report.enumeration:
+            sorted_entries = sorted(
+                report.enumeration.entries,
+                key=lambda e: e.ordering_key,
+            )
+            sorted_enum = EnumerationPayload(
+                state=report.enumeration.state,
+                causes=list(report.enumeration.causes),
+                entries=sorted_entries,
+            )
+
+        return cls.model_validate(
+            report.model_dump() | {
+                "findings": [f.model_dump() for f in sorted_findings],
+                "resolved_references": [r.model_dump() for r in sorted_refs],
+                "enumeration": (
+                    sorted_enum.model_dump() if sorted_enum else None
+                ),
+            }
+        )
+
+
+__all__ = [
+    "ConformanceFinding",
+    "ConformanceReport",
+    "EnumerationEntry",
+    "EnumerationPayload",
+    "EnumerationState",
+    "ExecutionStatusCounts",
+    "FindingExecutionStatus",
+    "FindingSeverity",
+    "ResolvedReference",
+    "SeverityCounts",
+    "Verdict",
+]

plm_skill_kernel-1.1.0/plm_skill_kernel/conformance/protocol.py

@@ -0,0 +1,46 @@
+"""ManifestProfileValidator typing.Protocol (MV1-DEC-018 Candidate 1).
+
+The Kernel owns this Protocol; implementations live in plm-skill-packages
+or are injected at runtime via the registration seam in ``__init__.py``.
+
+The Protocol is intentionally minimal — it accepts a snapshot root path
+and returns a :class:`ConformanceReport`. Validators MUST be fail-closed:
+internal errors produce a defect-level finding rather than silently passing.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .models import ConformanceReport
+
+
+@runtime_checkable
+class ManifestProfileValidator(Protocol):
+    """Contract that any profile validator implementation must satisfy.
+
+    Implementations register via
+    :func:`plm_skill_kernel.conformance.register_profile`.
+    """
+
+    @property
+    def profile_id(self) -> str:
+        """Canonical profile identifier, e.g. ``'manifest-v1'``."""
+        ...
+
+    @property
+    def profile_version(self) -> str:
+        """SemVer of the profile definition (e.g. ``'manifest-profile/1.0'``)."""
+        ...
+
+    def validate(self, snapshot_root: str) -> "ConformanceReport":
+        """Run full conformance validation against *snapshot_root*.
+
+        MUST be fail-closed: any internal error produces a defect-level
+        finding rather than silently passing. Never raises — all failures
+        are expressed as findings within the returned report.
+        """
+        ...
+
+
+__all__ = ["ManifestProfileValidator"]

{plm_skill_kernel-1.0.2 → plm_skill_kernel-1.1.0}/plm_skill_kernel.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plm-skill-kernel
-Version: 1.0.2
+Version: 1.1.0
 Summary: TracePulse PLM Skill Kernel — Wave 2 Conv A. Decorator-based Skill SDK + V1 in-process dispatcher + Kernel HTTP server stub matching CR.10 §7.bis (POST /v1/skills/{id}/invoke). Ships 3 starter skills (cleansing.normalise, cleansing.dedupe, bpmn.generate). Sibling of plm-engine-core; the two communicate over the V1.1 HTTP loopback (SKILL_KERNEL_LOOPBACK=on) — no Python-level coupling at the dispatch boundary.
 Author: TracePulse
 License: Proprietary
@@ -17,6 +17,8 @@ Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
 Requires-Dist: httpx<1,>=0.27; extra == "test"
+Provides-Extra: conformance
+Requires-Dist: plm-skill-packages; extra == "conformance"
 Provides-Extra: docs
 Requires-Dist: pdoc>=14.0; extra == "docs"
 

{plm_skill_kernel-1.0.2 → plm_skill_kernel-1.1.0}/plm_skill_kernel.egg-info/SOURCES.txt

@@ -11,6 +11,16 @@ plm_skill_kernel.egg-info/dependency_links.txt
 plm_skill_kernel.egg-info/entry_points.txt
 plm_skill_kernel.egg-info/requires.txt
 plm_skill_kernel.egg-info/top_level.txt
+plm_skill_kernel/conformance/__init__.py
+plm_skill_kernel/conformance/_cli.py
+plm_skill_kernel/conformance/_output_safety.py
+plm_skill_kernel/conformance/_serialize.py
+plm_skill_kernel/conformance/_terminal.py
+plm_skill_kernel/conformance/_verdict.py
+plm_skill_kernel/conformance/_version.py
+plm_skill_kernel/conformance/exit_codes.py
+plm_skill_kernel/conformance/models.py
+plm_skill_kernel/conformance/protocol.py
 plm_skill_kernel/sdk/__init__.py
 plm_skill_kernel/sdk/_registry.py
 plm_skill_kernel/sdk/context.py

{plm_skill_kernel-1.0.2 → plm_skill_kernel-1.1.0}/plm_skill_kernel.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
+plm-skill-conformance = plm_skill_kernel.conformance._cli:main
 plm-skill-kernel = plm_skill_kernel.server:_cli_entry

{plm_skill_kernel-1.0.2 → plm_skill_kernel-1.1.0}/plm_skill_kernel.egg-info/requires.txt

@@ -6,6 +6,9 @@ httpx>=0.27.0
 plm-engine-core
 plm-knowledge
 
+[conformance]
+plm-skill-packages
+
 [docs]
 pdoc>=14.0
 

{plm_skill_kernel-1.0.2 → plm_skill_kernel-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plm-skill-kernel"
-version = "1.0.2"
+version = "1.1.0"
 description = "TracePulse PLM Skill Kernel — Wave 2 Conv A. Decorator-based Skill SDK + V1 in-process dispatcher + Kernel HTTP server stub matching CR.10 §7.bis (POST /v1/skills/{id}/invoke). Ships 3 starter skills (cleansing.normalise, cleansing.dedupe, bpmn.generate). Sibling of plm-engine-core; the two communicate over the V1.1 HTTP loopback (SKILL_KERNEL_LOOPBACK=on) — no Python-level coupling at the dispatch boundary."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -44,6 +44,12 @@ test = [
     # HTTP loopback integration test (Q-W2A-4 = ASGI).
     "httpx>=0.27,<1",
 ]
+conformance = [
+    # FTR-2008 — the conformance CLI needs plm-skill-packages for the
+    # manifest-v1 profile validator implementation. Optional because the
+    # Protocol/models are testable standalone.
+    "plm-skill-packages",
+]
 docs = [
     # pdoc-based API reference site, built in CI on every push.
     # Ported from plm-shared (FTR-774 follow-up). See ci.yml::docs-build.
@@ -55,6 +61,10 @@ docs = [
 # `python -m plm_skill_kernel.server`. Default port 8100 keeps
 # clear of the backend at 8000.
 plm-skill-kernel = "plm_skill_kernel.server:_cli_entry"
+# FTR-2008 — conformance validation CLI (MV1-DEC-018 Candidate 1).
+# Separate entry from the server CLI to satisfy AC10 (unchanged behavior
+# when --profile is absent on the server CLI).
+plm-skill-conformance = "plm_skill_kernel.conformance._cli:main"
 
 [tool.setuptools.packages.find]
 where = ["."]
@@ -116,3 +126,10 @@ type = "forbidden"
 source_modules = ["plm_skill_kernel"]
 forbidden_modules = ["plm_accelerators"]
 ignore_imports = []
+
+[[tool.importlinter.contracts]]
+name = "conformance-must-not-import-sdk-wire-models"
+type = "forbidden"
+source_modules = ["plm_skill_kernel.conformance"]
+forbidden_modules = ["plm_skill_kernel.sdk"]
+ignore_imports = []