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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plm-skill-kernel
-Version: 1.0.2
+Version: 1.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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"]