bensz-skill-kernel 0.14.1__py3-none-any.whl

bensz_skill_kernel/__init__.py

@@ -0,0 +1,159 @@
+"""Minimal, append-only runtime kernel for Agent Skill task lifecycles."""
+
+from .runtime import (
+    CompletionError,
+    EventEnvelope,
+    EventLog,
+    IntegrityError,
+    IdempotencyConflict,
+    AuthorizationError,
+    InvalidTransition,
+    KernelError,
+    VALID_STATES,
+    reduce_events,
+)
+from .contracts import Artifact, Authorization, Contract, Effect, Requirement, Subject, RUNTIME_PROTOCOL_VERSION
+from .contract_packs import (
+    COMPONENT_RESULT_PROTOCOL,
+    CONTRACT_EXECUTION_PROTOCOL,
+    ComponentHandoff,
+    ComponentResult,
+    ContractBindingError,
+    ContractComponent,
+    ContractExecutionError,
+    ContractExecutionReport,
+    ContractPack,
+    ContractPackExecutor,
+)
+from .verifiers import (
+    Evidence,
+    CombinedVerifierRegistry,
+    FilesystemVerifierRegistry,
+    GateDecision,
+    PackRegistry,
+    VerifierPack,
+    VerifierRunner,
+    VerifierSpec,
+    VerifierDefinition,
+    VerifierRegistry,
+    VerificationRequest,
+    VerificationResult,
+    VerifierContractAdapter,
+    VerifierContractExecution,
+    apply_gate,
+    builtin_verifier_root,
+    normalize_result,
+    snapshot_evidence,
+    summarize_metrics,
+    normalize_requirements,
+)
+from .builtins import CITATION_TRUTH_FIT_SPEC, FILE_SPEC, build_builtin_registry, collect_markdown
+from .verifier_ids import validate_verifier_id
+from .state_ids import validate_state_id
+from .states import CombinedStateRegistry, FilesystemStateRegistry, META_STATE_PROTOCOL_VERSION, SKILL_STATE_DECLARATION_VERSION, SkillStateDeclaration, StateContractAdapter, StateDefinition, StateDefinitionError, StateExecutionError, StateExecutionResult, StateTransitionError, StateMachine, build_builtin_state_registry, build_state_registry, check_state_invariants, execute_state
+from .workspace import META_STATE_SNAPSHOT_VERSION, TaskWorkspace, WorkspaceError, WorkspacePaths, WORKSPACE_KINDS, WORKSPACE_PROTOCOL_VERSION, state_snapshot_hash, workspace_path
+
+__all__ = [
+    "CompletionError",
+    "EventEnvelope",
+    "EventLog",
+    "IntegrityError",
+    "IdempotencyConflict",
+    "AuthorizationError",
+    "InvalidTransition",
+    "KernelError",
+    "VALID_STATES",
+    "reduce_events",
+    "Artifact",
+    "Authorization",
+    "Contract",
+    "Effect",
+    "Requirement",
+    "Subject",
+    "RUNTIME_PROTOCOL_VERSION",
+    "COMPONENT_RESULT_PROTOCOL",
+    "CONTRACT_EXECUTION_PROTOCOL",
+    "ComponentHandoff",
+    "ComponentResult",
+    "ContractBindingError",
+    "ContractComponent",
+    "ContractExecutionError",
+    "ContractExecutionReport",
+    "ContractPack",
+    "ContractPackExecutor",
+    "Evidence",
+    "CombinedVerifierRegistry",
+    "FilesystemVerifierRegistry",
+    "VerifierRegistry",
+    "GateDecision",
+    "PackRegistry",
+    "VerifierPack",
+    "VerifierRunner",
+    "VerifierSpec",
+    "VerifierDefinition",
+    "VerificationRequest",
+    "VerificationResult",
+    "VerifierContractAdapter",
+    "VerifierContractExecution",
+    "apply_gate",
+    "builtin_verifier_root",
+    "normalize_result",
+    "snapshot_evidence",
+    "summarize_metrics",
+    "normalize_requirements",
+    "CITATION_TRUTH_FIT_SPEC",
+    "FILE_SPEC",
+    "build_builtin_registry",
+    "collect_markdown",
+    "validate_verifier_id",
+    "validate_state_id",
+    "FilesystemStateRegistry",
+    "CombinedStateRegistry",
+    "META_STATE_PROTOCOL_VERSION",
+    "SKILL_STATE_DECLARATION_VERSION",
+    "SkillStateDeclaration",
+    "StateDefinition",
+    "StateContractAdapter",
+    "StateDefinitionError",
+    "StateExecutionError",
+    "StateExecutionResult",
+    "StateTransitionError",
+    "StateMachine",
+    "build_builtin_state_registry",
+    "build_state_registry",
+    "execute_state",
+    "check_state_invariants",
+    "TaskWorkspace",
+    "WorkspaceError",
+    "WorkspacePaths",
+    "WORKSPACE_KINDS",
+    "WORKSPACE_PROTOCOL_VERSION",
+    "META_STATE_SNAPSHOT_VERSION",
+    "workspace_path",
+    "state_snapshot_hash",
+]
+
+def _distribution_version() -> str:
+    """Resolve the runtime version from the source metadata or installed wheel."""
+    from pathlib import Path
+    import importlib.metadata
+    import re
+
+    # During source-tree execution package metadata may describe an older
+    # globally installed wheel.  Prefer the adjacent pyproject as the source
+    # of truth in that case.
+    pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    try:
+        text = pyproject.read_text(encoding="utf-8")
+        match = re.search(r"(?m)^version\s*=\s*['\"]([^'\"]+)['\"]", text)
+        if match:
+            return match.group(1)
+    except OSError:
+        pass
+    try:
+        return importlib.metadata.version("bensz-skill-kernel")
+    except importlib.metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+__version__ = _distribution_version()

bensz_skill_kernel/atomic_verifiers.py

@@ -0,0 +1,93 @@
+"""Implementations for the small, domain-neutral atomic verifier packs.
+
+This module lives beside the directory contracts so reviewers can inspect the
+rules independently from the registry and runner plumbing.  Each directory's
+``scripts/verify.py`` is a thin JSON-stdio adapter around ``run_atomic``.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Mapping
+
+from bensz_skill_kernel.runtime import ALLOWED_TRANSITIONS, EventLog
+
+
+def _parts(request: Any) -> tuple[Mapping[str, Any], Mapping[str, Any]]:
+    if hasattr(request, "subject"):
+        return request.subject, request.context
+    return request.get("subject") or {}, request.get("context") or {}
+
+
+def _evidence_map(request: Any, evidence: Mapping[str, Any] | None) -> Mapping[str, Any]:
+    if evidence:
+        return evidence
+    if hasattr(request, "evidence"):
+        return {item.ref: item for item in request.evidence}
+    raw = request.get("evidence") or []
+    return {str(item.get("ref", index)): item for index, item in enumerate(raw) if isinstance(item, Mapping)}
+
+
+def run_atomic(name: str, request: Any, evidence: Mapping[str, Any] | None = None) -> Mapping[str, Any]:
+    subject, context = _parts(request)
+    evidence = _evidence_map(request, evidence)
+    if name == "contract-conformance":
+        required = tuple(context.get("required_fields", ()))
+        missing = [field for field in required if field not in subject]
+        return _result(not missing, {"required_fields": list(required), "missing": missing}, "missing-field", missing)
+    if name == "path-scope":
+        raw_paths = subject.get("paths") or ([subject["path"]] if subject.get("path") else [])
+        allowed = [Path(item).expanduser().resolve() for item in context.get("allowed_paths", ())]
+        violations = []
+        for raw in raw_paths:
+            target = Path(raw).expanduser().resolve()
+            # Scope is lexical after ``resolve()`` and must not depend on an
+            # allowed directory already existing.  Requiring ``is_dir()``
+            # made valid output paths fail before their parent was created.
+            if not any(target == root or root in target.parents for root in allowed):
+                violations.append(str(target))
+        return _result(not violations, {"paths": list(raw_paths), "violations": violations}, "path-out-of-scope", violations)
+    if name == "schema-conformance":
+        data = subject.get("data", subject)
+        schema = context.get("schema", {})
+        required = schema.get("required", ()) if isinstance(schema, Mapping) else ()
+        missing = [key for key in required if not isinstance(data, Mapping) or key not in data]
+        return _result(not missing, {"missing": missing}, "schema-required-field", missing)
+    if name == "diff-scope":
+        changed = set(subject.get("changed_paths", ()))
+        violations = sorted(changed - set(context.get("allowed_paths", ())))
+        return _result(not violations, {"changed": sorted(changed), "violations": violations}, "unexpected-change", violations)
+    if name == "secret-redaction":
+        raw = json.dumps(subject, ensure_ascii=False, default=str)
+        patterns = (r"[\"']?(?:api[_-]?key|token|password|cookie)[\"']?\s*[:=]\s*[\"']?[^,\s}\"']+", r"sk-[A-Za-z0-9_-]{8,}")
+        matches = [pattern for pattern in patterns if re.search(pattern, raw, re.IGNORECASE)]
+        return {"verdict": "fail" if matches else "pass", "facts": {"matched_patterns": len(matches)}, "findings": [{"id": "secret-detected", "verdict": "fail"}] if matches else []}
+    if name == "evidence-provenance":
+        def value(item: Any, key: str) -> Any:
+            return item.get(key) if isinstance(item, Mapping) else getattr(item, key, None)
+        invalid = [ref for ref, item in evidence.items() if not value(item, "source_type") or not value(item, "content_hash") or not value(item, "collected_at")]
+        return _result(not invalid, {"evidence_count": len(evidence)}, "missing-provenance", invalid)
+    if name == "event-integrity":
+        path = subject.get("path")
+        if not path:
+            return _result(False, {}, "missing-events-path", ["events"])
+        try:
+            count = len(EventLog(path).read())
+        except Exception as exc:
+            return {"verdict": "fail", "uncertainty_reason": str(exc), "findings": [{"id": "event-integrity", "verdict": "fail"}]}
+        return {"verdict": "pass", "facts": {"event_count": count}, "findings": []}
+    if name == "state-transition":
+        current, target = subject.get("current_state"), subject.get("target_state")
+        allowed = target in ALLOWED_TRANSITIONS.get(current, ())
+        return _result(allowed, {"current_state": current, "target_state": target}, "illegal-transition", [target] if not allowed else [])
+    if name == "task-completeness":
+        required = tuple(context.get("required_fields", ("artifacts", "verifications", "delivery_report")))
+        missing = [key for key in required if not subject.get(key)]
+        return _result(not missing, {"missing": missing}, "task-incomplete", missing)
+    raise ValueError(f"unknown atomic verifier: {name}")
+
+
+def _result(ok: bool, facts: Mapping[str, Any], finding_id: str, values: list[Any]) -> Mapping[str, Any]:
+    return {"verdict": "pass" if ok else "fail", "facts": dict(facts), "findings": [{"id": finding_id, "value": value, "verdict": "fail"} for value in values]}

bensz_skill_kernel/builtins.py

@@ -0,0 +1,114 @@
+"""Small, dependency-free verifier packs shipped with the kernel.
+
+Skills select these by stable id and tags.  Domain-specific packs can still be
+registered by a Skill, but common packs live here so Skills do not duplicate
+command, result, or Gate plumbing.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from typing import Any, Mapping
+
+from .verifiers import Evidence, PackRegistry, VerifierPack, VerifierSpec
+
+
+@lru_cache(maxsize=1)
+def _markdown_collector_module():
+    """Load the legacy Markdown API without keeping its implementation here."""
+    collector_path = (
+        Path(__file__).resolve().parent
+        / 'verifiers'
+        / 'markdown-link-integrity'
+        / 'scripts'
+        / 'collector.py'
+    )
+    spec = spec_from_file_location('bensz_skill_kernel._markdown_link_integrity_collector', collector_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f'cannot load Markdown collector: {collector_path}')
+    module = module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def collect_markdown(*args: Any, **kwargs: Any) -> dict[str, Any]:
+    """Backward-compatible proxy to the Markdown Verifier collector.
+
+    New code should invoke ``markdown-link-integrity`` through the filesystem
+    Verifier entrypoint instead of importing this compatibility API.
+    """
+    return _markdown_collector_module().collect_markdown(*args, **kwargs)
+
+
+@lru_cache(maxsize=1)
+def _atomic_module():
+    atomic_path = Path(__file__).resolve().parent / 'atomic_verifiers.py'
+    spec = spec_from_file_location('bensz_skill_kernel._atomic_verifiers', atomic_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f'cannot load atomic verifier rules: {atomic_path}')
+    module = module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+CITATION_TRUTH_FIT_SPEC = VerifierSpec(
+    verifier_id='bensz.evidence.citation-truth-fit',
+    version='1.0.0',
+    mode='hybrid',
+    capabilities=('evidence.identity', 'semantic.entailment', 'semantic.appropriateness'),
+    evidence_requirements=('subject_context', 'source_metadata', 'source_excerpt'),
+    uncertainty_policy={'missing_evidence': 'manual_review', 'engine_unavailable': 'unchecked'},
+    tags=('common', 'citation', 'semantic', 'evidence'),
+    aliases=('citation.truth-and-fit',),
+    metadata={'side_effects': 'none', 'requires_external_engine': True},
+)
+
+
+def _citation_engine_gap(request: Any, evidence: Mapping[str, Evidence]) -> Mapping[str, Any]:
+    return {
+        'execution_status': 'unchecked',
+        'verdict': 'unchecked',
+        'uncertainty_reason': 'semantic citation engine is not bundled with the kernel',
+        'evidence_refs': ['subject_context', 'source_metadata', 'source_excerpt'],
+        'model_or_engine': 'none',
+    }
+
+
+def _file_exists(request: Any, evidence: Mapping[str, Evidence]) -> Mapping[str, Any]:
+    path = request.subject.get('path')
+    exists = bool(path and Path(path).is_file())
+    return {'verdict': 'pass' if exists else 'fail', 'facts': {'path': path, 'exists': exists}, 'findings': [] if exists else [{'id': 'missing-file', 'severity': 'required', 'verdict': 'fail', 'message': f'file does not exist: {path}'}]}
+
+
+FILE_SPEC = VerifierSpec(
+    verifier_id='bensz.artifact.file-existence',
+    version='1.0.0',
+    mode='rule',
+    capabilities=('filesystem.read',),
+    tags=('common', 'filesystem', 'deterministic'),
+    aliases=('artifact.file-exists',),
+    metadata={'side_effects': 'none'},
+)
+
+
+def build_builtin_registry() -> PackRegistry:
+    registry = PackRegistry()
+    registry.register(VerifierPack(FILE_SPEC, rules=(('file-exists', _file_exists),)))
+    registry.register(VerifierPack(CITATION_TRUTH_FIT_SPEC, prompts=(('citation-semantics', _citation_engine_gap),)))
+    atomic = (
+        ("bensz.contract.conformance", "contract-conformance", "contract"),
+        ("bensz.artifact.path-scope", "path-scope", "artifact"),
+        ("bensz.artifact.schema-conformance", "schema-conformance", "artifact"),
+        ("bensz.source.diff-scope", "diff-scope", "source"),
+        ("bensz.security.secret-redaction", "secret-redaction", "security"),
+        ("bensz.evidence.provenance", "evidence-provenance", "evidence"),
+        ("bensz.runtime.event-integrity", "event-integrity", "runtime"),
+        ("bensz.runtime.state-transition", "state-transition", "runtime"),
+        ("bensz.runtime.task-completeness", "task-completeness", "runtime"),
+    )
+    for verifier_id, rule_name, tag in atomic:
+        rule = lambda request, evidence, name=rule_name: _atomic_module().run_atomic(name, request, evidence)
+        registry.register(VerifierPack(VerifierSpec(verifier_id, "1.0.0", "rule", tags=("common", tag, "deterministic")), rules=((rule_name, rule),)))
+    return registry