plm-skill-kernel 1.0.0__py3-none-any.whl

plm_skill_kernel/sdk/types.py

@@ -0,0 +1,86 @@
+"""V1 Skill wire shapes — frozen Pydantic v2 contract (CR.10 §7.bis).
+
+The Kernel HTTP server stub at ``POST /v1/skills/{id}/invoke`` accepts
+:class:`SkillInvokeRequest` and returns :class:`SkillInvokeResult`.
+The wire shape is deliberately a near-mirror of CR.10's
+``DispatchRequest`` / ``DispatchResult`` (in plm-engine-core) so the
+V1.1 HTTP loopback closure (D-CONV-M-4) is a straight pass-through.
+
+Decision #59 (Conv N / Q-N4 = Option α decorator). The wire shapes
+are independent of the authoring surface — a non-decorator skill (or
+a non-Python skill in V2.0+) would still produce + consume the same
+JSON.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _FrozenModel(BaseModel):
+    """Internal base — frozen + ``extra="forbid"`` to lock the wire shape.
+
+    Wave 2 V1 only adds optional fields with safe defaults; required-field
+    additions are a V2.0 break and need their own design lock.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class SkillInvokeRequest(_FrozenModel):
+    """V1 request body for ``POST /v1/skills/{id}/invoke``.
+
+    The skill ID lives in the URL path (``{id}``); the body carries
+    payload + version + an optional autonomy hint. The hint is purely
+    advisory — the Kernel does NOT re-run gating; that already happened
+    at the Core selector layer (CR.10).
+    """
+
+    payload: Dict[str, Any] = Field(default_factory=dict)
+    version: str = Field(min_length=1)
+    autonomy_hint: Optional[str] = Field(
+        default=None,
+        description=(
+            "Advisory autonomy level — 'L1' / 'L2' / 'L3'. "
+            "Skills MAY consult this to alter behaviour but MUST NOT "
+            "treat it as authoritative gating (gating happens at Core)."
+        ),
+    )
+
+
+class SkillErrorEnvelope(_FrozenModel):
+    """Typed error returned in :class:`SkillInvokeResult.error`.
+
+    Mirrors the shape of ``plm_shared.errors.ErrorEnvelope`` — the
+    ``error_code`` is a D-AUDIT-7 code (V1 = 57; new Skill-side codes
+    are reserved through ``CAPABILITY_*`` / ``SKILL_*`` / ``KERNEL_*``).
+    """
+
+    error_code: str = Field(min_length=1)
+    message: str = Field(min_length=1)
+    detail: Optional[Dict[str, Any]] = None
+
+
+class SkillInvokeResult(_FrozenModel):
+    """V1 response body.
+
+    Exactly one of ``result`` or ``error`` is populated when ``ok``
+    matches. The ``cancelled`` flag is set when a run was cancelled
+    mid-flight via the W0.3 / CR.1b RunTaskTracker surface; the
+    ``deferred_to`` field carries the upstream story ID when the
+    Kernel-side deferral path activates.
+    """
+
+    ok: bool
+    result: Optional[Dict[str, Any]] = None
+    error: Optional[SkillErrorEnvelope] = None
+    deferred_to: Optional[str] = None
+    cancelled: Optional[bool] = None
+
+
+__all__ = [
+    "SkillErrorEnvelope",
+    "SkillInvokeRequest",
+    "SkillInvokeResult",
+]

plm_skill_kernel/server.py

@@ -0,0 +1,173 @@
+"""Kernel HTTP server stub — FastAPI app exposing CR.10 §7.bis.
+
+Routes:
+
+* ``POST /v1/skills/{skill_id}/invoke`` — primary dispatch surface.
+  Body: :class:`SkillInvokeRequest`. Response: :class:`SkillInvokeResult`.
+* ``GET /v1/skills`` — introspection — list registered skills.
+* ``GET /v1/health`` — liveness / readiness probe.
+
+Headers honoured on the dispatch endpoint:
+
+* ``X-Core-Caller: <UUID>`` — identifies the calling Core instance.
+  Threaded through to :class:`SkillContext.core_caller`. NOT validated
+  for V1 — a real auth contract lands at V1.1 (analogous to the
+  middleware pattern from CR.0 PR-2 in plm-engine-core).
+* ``Idempotency-Key: <uuid>`` — propagated to the SDK context; skills
+  MAY use it to dedupe side-effects.
+* ``traceparent`` — W3C trace; propagated to ``ctx.trace_id``.
+
+Q-W2A-3 (operator decision): the server runs standalone via
+``python -m plm_skill_kernel`` on port 8100 by default. The ``_cli_entry``
+function below is the ``plm-skill-kernel`` console-script entry.
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from fastapi import FastAPI, Header, HTTPException, Path
+from fastapi.responses import JSONResponse
+
+from .dispatcher import InProcessDispatcher
+from .registry import load_starter_skills
+from .sdk._registry import get_registry
+from .sdk.context import SkillContext
+from .sdk.types import SkillInvokeRequest, SkillInvokeResult
+
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_PORT = 8100
+
+
+def build_app(*, load_skills: bool = True) -> FastAPI:
+    """Construct the Kernel FastAPI app.
+
+    ``load_skills`` defaults to True so production callers get a
+    fully-wired server out of the box. Tests that want to register a
+    custom set of skills (or none) pass ``load_skills=False`` and
+    populate the SDK registry themselves.
+    """
+    app = FastAPI(
+        title="plm-skill-kernel",
+        version="0.1.0-alpha",
+        description=(
+            "TracePulse Skill Kernel — Wave 2 Conv A. "
+            "POST /v1/skills/{id}/invoke matches CR.10 §7.bis."
+        ),
+        # Disable docs in V1 — the OpenAPI contract is published by
+        # plm-engine-core's CR.8 surface; the Kernel's wire shape is
+        # locked separately. V1.1 may re-enable when CR.8 widens to
+        # cover Kernel routes.
+        docs_url=None,
+        redoc_url=None,
+    )
+
+    if load_skills:
+        load_starter_skills()
+
+    dispatcher = InProcessDispatcher()
+
+    @app.get("/v1/health")
+    async def _health() -> Dict[str, Any]:
+        return {
+            "liveness": "ok",
+            "readiness": "ok",
+            "skill_count": len(get_registry().list_all()),
+        }
+
+    @app.get("/v1/skills")
+    async def _list_skills() -> Dict[str, List[Dict[str, Any]]]:
+        skills = [
+            {
+                "skill_id": e.skill_id,
+                "version": e.version,
+                "description": e.description,
+                "min_autonomy": e.min_autonomy,
+                "streaming": e.streaming,
+                "hitl_required": e.hitl_required,
+            }
+            for e in get_registry().list_all()
+        ]
+        return {"skills": skills}
+
+    @app.post(
+        "/v1/skills/{skill_id}/invoke",
+        response_model=SkillInvokeResult,
+    )
+    async def _invoke(
+        request: SkillInvokeRequest,
+        skill_id: str = Path(..., min_length=1),
+        x_core_caller: Optional[str] = Header(default=None),
+        idempotency_key: Optional[str] = Header(default=None),
+        traceparent: Optional[str] = Header(default=None),
+        x_tenant_id: Optional[str] = Header(default=None),
+        x_run_id: Optional[str] = Header(default=None),
+    ) -> SkillInvokeResult:
+        # Build the per-call context. Tenant + run identifiers come
+        # from headers — V1 trusts them; V1.1 will validate against
+        # the X-Core-Caller signature.
+        ctx = SkillContext(
+            skill_id=skill_id,
+            skill_version=request.version,
+            tenant_id=x_tenant_id or "anonymous",
+            run_id=x_run_id,
+            trace_id=traceparent,
+            autonomy_level=request.autonomy_hint,
+            idempotency_key=idempotency_key,
+            core_caller=x_core_caller,
+        )
+        result = await dispatcher.dispatch(skill_id, request, context=ctx)
+        return result
+
+    return app
+
+
+# Module-level app instance for `uvicorn plm_skill_kernel.server:app`.
+# Construction is lazy — tests that don't want skill auto-load can
+# import `build_app` instead.
+app = build_app()
+
+
+def _cli_entry(argv: Optional[List[str]] = None) -> None:
+    """Console-script entry — ``plm-skill-kernel`` / ``python -m plm_skill_kernel``.
+
+    Q-W2A-3 picked the standalone launch pattern. Default port 8100;
+    can be overridden via ``--port`` or ``SKILL_KERNEL_PORT`` env.
+    """
+    parser = argparse.ArgumentParser(prog="plm-skill-kernel")
+    parser.add_argument(
+        "--host", default=os.environ.get("SKILL_KERNEL_HOST", "127.0.0.1")
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("SKILL_KERNEL_PORT", str(DEFAULT_PORT))),
+    )
+    parser.add_argument(
+        "--log-level",
+        default=os.environ.get("SKILL_KERNEL_LOG_LEVEL", "info"),
+    )
+    args = parser.parse_args(argv)
+
+    # uvicorn import is here so module import (used by tests via
+    # `from plm_skill_kernel.server import build_app`) never pays the
+    # uvicorn startup cost.
+    import uvicorn
+
+    logger.info(
+        "plm-skill-kernel starting host=%s port=%s", args.host, args.port
+    )
+    uvicorn.run(
+        "plm_skill_kernel.server:app",
+        host=args.host,
+        port=args.port,
+        log_level=args.log_level,
+    )
+
+
+__all__ = ["DEFAULT_PORT", "app", "build_app", "_cli_entry"]

plm_skill_kernel/skills/__init__.py

@@ -0,0 +1,16 @@
+"""Wave 2 starter skills — nested-by-skill-ID layout (Q-W2A-1).
+
+Subpackages:
+
+* ``cleansing.normalise`` — pure-function normalisation (L2).
+* ``cleansing.dedupe``    — pure-function fuzzy dedupe (L2).
+* ``bpmn.generate``       — thin proxy to ``agents/process_generator``
+                            (L1 suggest-only). Per Q-W2A-2: the
+                            cascade Gemini → Azure → Mock fallback
+                            is preserved by reuse, NOT by harvest.
+
+Per Decision #60, ``documents.parse`` + ``agents.suggest`` land in
+Wave 3. The current ``__init__.py`` is intentionally empty — skills
+register themselves at import time via the ``@skill`` decorator, and
+the boot fan-out lives in :mod:`plm_skill_kernel.registry`.
+"""

plm_skill_kernel/skills/agents/__init__.py

@@ -0,0 +1,13 @@
+"""Wave 3 Conv A — ``agents.*`` skill namespace.
+
+Subpackages:
+
+* ``agents.suggest`` — thin proxy to ``services.agent_analysis_service``.
+  L1 — surfaces 3 contextual modeling suggestions for a BPMN process or
+  for a free-text document. Caller renders the suggestions as one-tap
+  prompts in the Workbench / Studio reviewer UI.
+
+The ``__init__.py`` is intentionally empty — skills register themselves at
+import time via the ``@skill`` decorator; the boot fan-out lives in
+:mod:`plm_skill_kernel.registry`.
+"""

plm_skill_kernel/skills/agents/suggest.py

@@ -0,0 +1,191 @@
+"""``agents.suggest`` / 1.0.0 / L1 — thin proxy to agent suggestion helpers.
+
+Q-W3A-3 (Wave 3 Conv A) picked the thin-proxy shape: the skill imports +
+delegates to ``services.agent_analysis_service`` (the legacy LLM-backed
+suggestion helpers) at invocation time. Mirrors the ``bpmn.generate``
+Decision #62 precedent — the V1 dispatch boundary is a lazy-import
+contract; V1.1 will replace it with an MCP-bound out-of-process call.
+
+V1 contract:
+
+    Input payload:
+        {
+            "mode":       "agent" | "plan" | "from_text" | "from_text_plan",
+            "bpmn_xml":   str | None,    # required when mode in {agent, plan}
+            "text":       str | None,    # required when mode in {from_text, from_text_plan}
+            "doc_name":   str | None,    # required when mode in {from_text, from_text_plan}
+        }
+
+    Output:
+        {
+            "mode":         str,
+            "suggestions":  [str, ...],   # at most 3 suggestions
+            "count":        int,
+        }
+
+L1 (suggest-only) — the skill returns a 3-suggestion list for the
+caller's UI; it does NOT persist or commit. The caller (Studio /
+Workbench reviewer UI) renders each suggestion as a one-tap prompt.
+
+Architecture note: ``services.agent_analysis_service`` is a backend
+module (``02_App/backend/services/``) NOT under ``plm_skill_kernel`` or
+``plm_engine_core``. Importing it here creates a runtime dependency on
+the backend Python path — the import is therefore done LAZILY inside
+the function body so:
+
+  1. The plm-skill-kernel package itself can be imported without
+     requiring the backend on PYTHONPATH (e.g. a clean container image
+     of the kernel-only service).
+  2. Tests that don't exercise suggestion generation don't pay the
+     import cost (and don't require the backend deps to be installed).
+
+The lazy-import pattern is the V1 dispatch-boundary contract; V1.1 will
+replace it with an MCP-bound out-of-process call once the backend's
+analysis entry points themselves migrate to an MCP server.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+from plm_skill_kernel import SkillContext, skill
+
+
+logger = logging.getLogger(__name__)
+
+
+# Frozen V1 mode set — additive change only (no rename of existing values).
+_VALID_MODES = frozenset({
+    "agent",
+    "plan",
+    "from_text",
+    "from_text_plan",
+})
+
+
+def _ensure_backend_on_path() -> None:
+    """Best-effort: add ``02_App/backend`` to ``sys.path`` if it isn't.
+
+    Same pattern as :mod:`plm_skill_kernel.skills.bpmn.generate` — kept
+    duplicated rather than extracted to a helper so each skill stays
+    self-contained at import time (no cross-skill coupling at the SDK
+    registry layer).
+    """
+    here = Path(__file__).resolve()
+    # plm_skill_kernel/skills/agents/suggest.py → 4× parents = plm-skill-kernel/
+    # 5× parents = 02_App/.
+    candidate = here.parents[4] / "backend"
+    if candidate.exists():
+        candidate_str = str(candidate)
+        if candidate_str not in sys.path:
+            sys.path.insert(0, candidate_str)
+
+
+@skill(
+    id="agents.suggest",
+    version="1.0.0",
+    description=(
+        "Generate 3 contextual modelling-suggestion prompts from either "
+        "a BPMN process or a free-text document. Suggest-only (L1) — "
+        "caller renders the result as one-tap prompts. Wraps "
+        "services.agent_analysis_service helpers."
+    ),
+    min_autonomy="L1",
+    streaming=False,
+    hitl_required=False,
+)
+async def agents_suggest(
+    payload: Dict[str, Any], ctx: SkillContext
+) -> Dict[str, Any]:
+    """Thin proxy to ``services.agent_analysis_service.generate_suggestions*``.
+
+    Validates the V1 contract surface (``mode`` is required + the
+    corresponding ``bpmn_xml`` / ``text`` payload is the right shape)
+    before reaching the backend; once the proxy fires, the legacy LLM
+    helpers own the rest.
+    """
+    mode = payload.get("mode")
+    if not isinstance(mode, str) or mode not in _VALID_MODES:
+        raise ValueError(
+            f"agents.suggest: payload['mode'] must be one of "
+            f"{sorted(_VALID_MODES)}; got {mode!r}"
+        )
+
+    if mode in {"agent", "plan"}:
+        bpmn_xml = payload.get("bpmn_xml")
+        if not isinstance(bpmn_xml, str) or not bpmn_xml:
+            raise ValueError(
+                "agents.suggest: payload['bpmn_xml'] must be a non-empty "
+                "string when mode is 'agent' or 'plan'"
+            )
+    else:
+        bpmn_xml = None  # not used in from_text* modes
+
+    if mode in {"from_text", "from_text_plan"}:
+        text = payload.get("text")
+        if not isinstance(text, str):
+            raise ValueError(
+                "agents.suggest: payload['text'] must be a string when "
+                "mode is 'from_text' or 'from_text_plan'"
+            )
+        doc_name = payload.get("doc_name")
+        if not isinstance(doc_name, str) or not doc_name:
+            raise ValueError(
+                "agents.suggest: payload['doc_name'] must be a non-empty "
+                "string when mode is 'from_text' or 'from_text_plan'"
+            )
+    else:
+        text = None
+        doc_name = None
+
+    _ensure_backend_on_path()
+    try:
+        from studio_backend.services.agent_analysis_service import (  # type: ignore[import-not-found]
+            generate_suggestions,
+            generate_suggestions_for_plan,
+            generate_suggestions_from_text,
+        )
+    except ImportError as exc:
+        raise RuntimeError(
+            "agents.suggest: backend module `services.agent_analysis_service` "
+            "is not importable from this kernel process. The V1 thin-"
+            "proxy shape requires the backend on PYTHONPATH; install "
+            "the backend editable or run via 02_App/run.py."
+        ) from exc
+
+    logger.info(
+        "agents.suggest dispatching mode=%s tenant=%s run_id=%s",
+        mode,
+        ctx.tenant_id,
+        ctx.run_id,
+    )
+
+    suggestions: List[str]
+    if mode == "agent":
+        result = await generate_suggestions(bpmn_xml or "", mode="agent")
+        suggestions = list(result) if isinstance(result, list) else []
+    elif mode == "plan":
+        result = await generate_suggestions(bpmn_xml or "", mode="plan")
+        suggestions = list(result) if isinstance(result, list) else []
+    elif mode == "from_text":
+        result = await generate_suggestions_from_text(text or "", doc_name or "")
+        suggestions = list(result) if isinstance(result, list) else []
+    else:  # from_text_plan
+        result = await generate_suggestions_for_plan(text or "", doc_name or "")
+        suggestions = list(result) if isinstance(result, list) else []
+
+    # V1 contract: stringify defensively + cap at 3 (matches the legacy
+    # helpers' contract). The legacy helpers already enforce the cap;
+    # we re-apply here so a future helper drift doesn't widen this skill.
+    suggestions = [str(s) for s in suggestions if s][:3]
+
+    return {
+        "mode": mode,
+        "suggestions": suggestions,
+        "count": len(suggestions),
+    }
+
+
+__all__ = ["agents_suggest"]

plm_skill_kernel/skills/bpmn/__init__.py

@@ -0,0 +1,9 @@
+"""BPMN skills namespace — ``bpmn.generate`` (Wave 2 starter, L1).
+
+Per Q-W2A-2 (Conv N close), ``bpmn.generate`` is a thin proxy to the
+existing ``agents/process_generator.generate_process`` cascade. The
+cascade Gemini → Azure → Mock is the only legitimate fallback per
+CLAUDE.md "Strict model dispatch" exception; preserving it via reuse
+keeps the cascade in one place rather than duplicating it inside the
+Skill body.
+"""

plm_skill_kernel/skills/bpmn/generate.py

@@ -0,0 +1,147 @@
+"""``bpmn.generate`` / 1.0.0 / L1 — thin proxy to the BPMN cascade.
+
+Q-W2A-2 (Conv N close) picked the thin-proxy shape: the skill imports
++ delegates to ``agents/process_generator.generate_process`` at
+invocation time. The cascade Gemini → Azure → Mock is the only
+legitimate fallback per CLAUDE.md "Strict model dispatch" exception;
+proxying preserves it without duplication.
+
+V1 contract:
+
+    Input payload:
+        {
+            "content":      str,       # required — CSV / text content
+            "source_type":  str,       # required — "mining-csv" or "text"
+        }
+
+    Output:
+        {
+            "name":         str,
+            "description":  str,
+            "bpmnXml":      str,
+            "miningMetrics":[ {...}, ... ],
+        }
+
+L1 (suggest-only) — the skill returns BPMN XML for the caller to
+review; it does NOT persist or commit.
+
+Architecture note: ``agents.process_generator`` is a backend module
+(``02_App/backend/agents/``) NOT under ``plm_skill_kernel`` or
+``plm_engine_core``. Importing it here creates a runtime dependency
+on the backend Python path — the import is therefore done LAZILY
+inside the function body so:
+
+  1. The plm-skill-kernel package itself can be imported without
+     requiring the backend on PYTHONPATH (e.g. a clean container
+     image of the kernel-only service).
+  2. Tests that don't exercise the BPMN cascade do not pay the
+     import cost (and don't require the backend deps to be installed).
+
+The lazy-import pattern is the V1 dispatch-boundary contract; V1.1
+will replace it with an MCP-bound out-of-process call once the
+backend's BPMN entry point itself migrates to an MCP server.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+from plm_skill_kernel import SkillContext, skill
+
+
+logger = logging.getLogger(__name__)
+
+
+def _ensure_backend_on_path() -> None:
+    """Best-effort: add ``02_App/backend`` to ``sys.path`` if it isn't.
+
+    V1 reality: the kernel runs out of the same monorepo as the
+    backend; ``02_App/run.py`` is the canonical dev launcher and it
+    does NOT yet add backend/ to PYTHONPATH for the kernel process.
+    The lazy fix-up keeps a kernel-only deployment viable (it'll fail
+    fast at the import site below with a clear error message rather
+    than a confusing ImportError) AND keeps the dev path working.
+
+    Wave 2 Conv B + the carve will replace this with a proper backend
+    entry-point package if the proxy survives that long.
+    """
+    here = Path(__file__).resolve()
+    # plm_skill_kernel/skills/bpmn/generate.py → 4× parents = plm-skill-kernel/
+    # 5× parents = 02_App/.
+    candidate = here.parents[4] / "backend"
+    if candidate.exists():
+        candidate_str = str(candidate)
+        if candidate_str not in sys.path:
+            sys.path.insert(0, candidate_str)
+
+
+@skill(
+    id="bpmn.generate",
+    version="1.0.0",
+    description=(
+        "Generate a BPMN 2.0 process from CSV mining data or natural "
+        "language. Suggest-only (L1) — caller reviews + commits. "
+        "Wraps the legitimate Gemini → Azure → Mock cascade."
+    ),
+    min_autonomy="L1",
+    streaming=False,
+    hitl_required=False,
+)
+async def bpmn_generate(
+    payload: Dict[str, Any], ctx: SkillContext
+) -> Dict[str, Any]:
+    """Thin proxy to ``agents.process_generator.generate_process``.
+
+    Validates the V1 contract surface (``content`` + ``source_type``
+    are required + must be the right shapes) before reaching the
+    backend; once the proxy fires, the cascade owns the rest.
+    """
+    content = payload.get("content")
+    source_type = payload.get("source_type")
+    if not isinstance(content, str) or not content:
+        raise ValueError(
+            "bpmn.generate: payload['content'] must be a non-empty string"
+        )
+    if not isinstance(source_type, str) or not source_type:
+        raise ValueError(
+            "bpmn.generate: payload['source_type'] must be a non-empty string"
+        )
+
+    _ensure_backend_on_path()
+    try:
+        from plm_skill_packages.process_generator import generate_process  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise RuntimeError(
+            "bpmn.generate: backend module `agents.process_generator` "
+            "is not importable from this kernel process. The V1 thin-"
+            "proxy shape requires the backend on PYTHONPATH; install "
+            "the backend editable or run via 02_App/run.py."
+        ) from exc
+
+    logger.info(
+        "bpmn.generate dispatching content_chars=%s source_type=%s "
+        "tenant=%s run_id=%s",
+        len(content),
+        source_type,
+        ctx.tenant_id,
+        ctx.run_id,
+    )
+    result = await generate_process(content, source_type)
+
+    # ``generate_process`` returns a dict with ``name``, ``description``,
+    # ``bpmnXml``, ``miningMetrics``. V1 contract is the same shape;
+    # pass-through unchanged. Defensive: if the cascade hands back an
+    # unexpected shape, surface a structured error rather than letting
+    # the dispatcher's generic dict-check fire (which loses context).
+    if not isinstance(result, dict):
+        raise RuntimeError(
+            f"bpmn.generate: process_generator returned {type(result).__name__}; "
+            "expected dict"
+        )
+
+    return result
+
+
+__all__ = ["bpmn_generate"]

plm_skill_kernel/skills/cleansing/__init__.py

@@ -0,0 +1,10 @@
+"""Cleansing skills namespace — ``cleansing.normalise`` + ``cleansing.dedupe``.
+
+Both skills are pure-function in V1: no DB reach-in, no LLM call,
+no side effects. The harvest sources (``services/cleansing_service.py``
++ ``agents/process_generator`` normalisation surface) carry heavy
+DB + service coupling that does NOT belong inside a Skill body — V1
+ships the canonical normalisation/dedupe primitives at the Kernel
+layer; the backend cleansing service can call into the Kernel via
+the V1.1 HTTP loopback once the carve at Wave 2 Conv B lands.
+"""