intent.py

# Copyright 2026 McLeod Interactive Group LLC
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#     http://www.apache.org/licenses/LICENSE-2.0
# Distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied.

"""
Intent alignment — PUBLIC INTERFACE with a reference stub.

CSP Specification §5.5 requires that the authority anchor refuse a keystone
handshake or succession when the principal's stated intent materially
conflicts with the founding intent bound into K0. A valid physical key with
misaligned intent is a *harder* refusal than a failed key: it signals
potential authority capture rather than simple credential loss.

WHAT SHIPS PUBLICLY (this file):
  * the interface every alignment engine must implement, and
  * a reference stub (`DigestMatchAligner`) that does an exact match of the
    ten founding-answer digest. It is correct and auditable, but it is NOT
    the production capture-detection logic.

WHAT STAYS PRIVATE (not in this repository):
  * McLeod Interactive Group's ten founding questions and canonical answers,
  * the semantic-fidelity scorer that decides how close a successor's
    answers must be, and how authority-capture is distinguished from an
    honest paraphrase.
That scorer and question set are MIG core IP. A deployment plugs its own
aligner in via `set_aligner()`; the public protocol never needs to see it.

To integrate a private aligner, implement `IntentAligner` in a module that
lives OUTSIDE this repository and register it at vault startup:

    from cooren_signal_protocol import intent
    from mig_private.aligner import MIGSemanticAligner   # private, not shipped
    intent.set_aligner(MIGSemanticAligner(...))

If no private aligner is registered, the vault falls back to the stub and
logs that it is running in reference mode.
"""
from __future__ import annotations

import hashlib
import json
from typing import Protocol, runtime_checkable


@runtime_checkable
class IntentAligner(Protocol):
    """The seam between the public protocol and private alignment logic.

    A conforming aligner decides two things:
      * genesis: are these founding answers acceptable to bind into K0?
      * succession: does a successor's answers align closely enough with the
        founding intent to re-derive the keystone, or is this capture?
    Implementations may be arbitrarily sophisticated; the protocol only
    depends on this surface.
    """

    def founding_digest(self, answers: dict) -> str:
        """Return the digest bound into K0 at genesis for `answers`."""
        ...

    def check_succession(self, founding_digest: str, answers: dict) -> "AlignmentResult":
        """Decide whether `answers` align with the bound founding intent."""
        ...


class AlignmentResult:
    """Outcome of an alignment check. `ok` gates the action; `score` and
    `reason` are for the audit log. `capture_suspected` is the §5.5 harder
    refusal: a well-formed but misaligned intent."""

    __slots__ = ("ok", "score", "reason", "capture_suspected")

    def __init__(self, ok: bool, score: float = 0.0, reason: str = "",
                 capture_suspected: bool = False):
        self.ok = ok
        self.score = score
        self.reason = reason
        self.capture_suspected = capture_suspected

    def __repr__(self):
        return (f"AlignmentResult(ok={self.ok}, score={self.score:.3f}, "
                f"capture_suspected={self.capture_suspected}, "
                f"reason={self.reason!r})")


class DigestMatchAligner:
    """REFERENCE STUB. Exact-match on the founding-answer digest.

    This is deliberately not the production logic. It accepts a successor
    only if their answers are byte-identical to the founding answers, which
    is a correct but brittle floor: it cannot recognize an honest paraphrase
    and cannot detect capture in a near-miss. Production deployments replace
    it with a private semantic aligner via `set_aligner()`.
    """

    mode = "reference-stub"

    def founding_digest(self, answers: dict) -> str:
        return hashlib.sha256(
            json.dumps(answers, sort_keys=True).encode()).hexdigest()

    def check_succession(self, founding_digest: str, answers: dict) -> AlignmentResult:
        candidate = self.founding_digest(answers)
        if candidate == founding_digest:
            return AlignmentResult(ok=True, score=1.0, reason="exact digest match")
        # A stub cannot tell capture from paraphrase, so it refuses plainly
        # and does NOT assert capture — that judgment needs the real scorer.
        return AlignmentResult(ok=False, score=0.0,
                               reason="digest mismatch (reference stub cannot "
                                      "score semantic fidelity)",
                               capture_suspected=False)


# ---- registry ------------------------------------------------------------

_ALIGNER: IntentAligner = DigestMatchAligner()


def set_aligner(aligner: IntentAligner) -> None:
    """Register a (typically private) alignment engine. Call once at vault
    startup, before genesis or any succession."""
    global _ALIGNER
    _ALIGNER = aligner


def get_aligner() -> IntentAligner:
    return _ALIGNER


def is_reference_mode() -> bool:
    return getattr(_ALIGNER, "mode", "") == "reference-stub"