postmo 1.0.0__py3-none-any.whl

postmo/__init__.py

@@ -0,0 +1,49 @@
+"""postmo — hold a messy situation without resolving it.
+
+Five audit disciplines, enforced as a linter where they're mechanical
+and as explicit operator protocol where they need judgment:
+
+1. Hold contradictions as contradictions (parallel sentences, never "X, but Y").
+2. Track people as time-indexed states, never categorical verdicts.
+3. Type every correction: detail vs core-claim.
+4. Never supply motive or causality the teller didn't state.
+5. Self-check every output for softened threat language, supplied
+   generous interpretations, dropped contradictions, resolved ambivalence.
+
+Two modes: direct audit (the headline — "don't resolve this, just hold
+it", no engine needed) and overlay on the interrogation engine's
+Decompose/Collide phases. Either way the canonical artifact is the
+audit record: full structured data the next session can load, with
+timestamps. The audit never resolves — the record schema rejects
+synthesis/resolution/verdict sections.
+"""
+
+from .disciplines import DISCIPLINES, D1, D2, D3, D4, D5, discipline_name
+from .evidence import (
+    EvidenceError, EvidenceItem, check_matches_engine, normalize_tag, tag_list,
+)
+from .overlay import NEVER, attachment_for, describe_contract
+from .record import (
+    PROTOCOL, AuditRecord, DisciplineEntry, RecordError, check_stand_down, parse,
+    utc_now,
+)
+from .scans import (
+    Correction, CorrectionCandidate, HeldTension, MotiveFlag, PersonState,
+    ScanError, ScanReport, SofteningFlag, VerdictWordHit,
+    detect_softening, detect_supplied_motive, find_correction_candidates,
+    find_subordinators, find_verdict_words, scan_text,
+)
+
+__all__ = [
+    "DISCIPLINES", "D1", "D2", "D3", "D4", "D5", "discipline_name",
+    "EvidenceError", "EvidenceItem", "check_matches_engine",
+    "normalize_tag", "tag_list",
+    "NEVER", "attachment_for", "describe_contract",
+    "PROTOCOL", "AuditRecord", "DisciplineEntry", "RecordError",
+    "check_stand_down", "parse", "utc_now",
+    "Correction", "CorrectionCandidate", "HeldTension", "MotiveFlag",
+    "PersonState", "ScanError", "ScanReport", "SofteningFlag",
+    "VerdictWordHit", "detect_softening", "detect_supplied_motive",
+    "find_correction_candidates", "find_subordinators", "find_verdict_words",
+    "scan_text",
+]

postmo/disciplines.py

@@ -0,0 +1,138 @@
+"""The five audit disciplines, stated once.
+
+An audit is not a narrative: a narrative resolves tension toward a
+single coherent story; an audit holds the actual shape of what's been
+said — including the parts that don't resolve — and tracks it
+accurately as it changes.
+
+Each discipline carries its code/operator split explicitly:
+`mechanical` is what `scans.py` checks; `operator` is what needs a
+human or model judgment and stays protocol, not code. The split is
+honest, not aspirational — a mechanical check that fired is a finding;
+an operator check is a responsibility.
+"""
+
+from __future__ import annotations
+
+D1 = 1  # hold contradictions as contradictions
+D2 = 2  # track person-state as time-indexed, not categorical
+D3 = 3  # distinguish detail-correction from core-claim correction
+D4 = 4  # don't supply motive or causality the teller didn't state
+D5 = 5  # self-check for softening and evasion — including your own
+
+DISCIPLINES: dict[int, dict[str, str]] = {
+    D1: {
+        "name": "hold-contradictions",
+        "rule": (
+            "When two stated things are in tension, do not pick one side, "
+            "do not synthesize a third thing that subordinates one to the "
+            "other, and do not flag the tension as a problem needing "
+            "resolution. Both halves stay live. If a synthesis is true, "
+            "the teller states it — never supply it on their behalf."
+        ),
+        "mechanical": (
+            "Held tensions must be parallel non-subordinating sentences "
+            "('X is true. Y is also true.') — the subordinator scan in "
+            "scans.py rejects 'X, but/however/which means Y'."
+        ),
+        "operator": (
+            "Recognizing that two statements ARE in tension (the scan "
+            "checks grammar, not meaning); refusing to tidy the tension "
+            "in surrounding prose; leaving silence where no resolving "
+            "sentence is needed."
+        ),
+    },
+    D2: {
+        "name": "time-indexed-person-states",
+        "rule": (
+            "People are not 'good' or 'bad', 'safe' or 'dangerous' as fixed "
+            "labels — they are in different states at different points, and "
+            "all of those states are real simultaneously. Summarize "
+            "sequences of states, never verdicts on persons."
+        ),
+        "mechanical": (
+            "PersonState requires when + person + state, all non-empty; "
+            "the verdict-word scan flags permanent-label language "
+            "('he is a liar') for operator review."
+        ),
+        "operator": (
+            "Resisting the pull to declare one state 'the mask' and another "
+            "'the truth'; keeping the sequence ordered and complete."
+        ),
+    },
+    D3: {
+        "name": "correction-typing",
+        "rule": (
+            "Detail correction: a particular fact is revised (a time, an "
+            "object, a peripheral sequence detail) — it does not touch any "
+            "core claim standing elsewhere. Core-claim correction: a "
+            "decision, boundary, conclusion, or central assertion is "
+            "revised. Never let a detail correction trigger re-litigation "
+            "of an uncorrected core claim. If ambiguous which kind, ask "
+            "rather than guess."
+        ),
+        "mechanical": (
+            "Correction records accept only 'detail' or 'core-claim'; the "
+            "correction-candidate scan flags correction-like sentences "
+            "('actually…', 'no wait…', 'to be clear…') that haven't been "
+            "typed yet."
+        ),
+        "operator": (
+            "Typing ambiguous corrections (ask, don't guess); holding the "
+            "line that a detail fix does not reopen standing core claims."
+        ),
+    },
+    D4: {
+        "name": "no-supplied-motive",
+        "rule": (
+            "Track what happened and what was said — not why, unless the "
+            "teller assigns the why. 'He tackled you because he panicked' "
+            "is an invented motive, even if plausible. State the observed "
+            "sequence: who did what, in what order. A directly requested "
+            "read on motive is a flagged guess ('if I had to guess…'), "
+            "never narrated as settled fact."
+        ),
+        "mechanical": (
+            "The motive scan flags causal/motive attributions ('because he "
+            "panicked', 'driven by', 'in order to') that carry no "
+            "attribution marker ('he said', 'according to', quotes) and no "
+            "explicit guess-flag."
+        ),
+        "operator": (
+            "The final call on whether a flagged attribution was actually "
+            "supplied by the teller in surrounding context the scan can't "
+            "see; keeping flagged guesses flagged."
+        ),
+    },
+    D5: {
+        "name": "softening-self-check",
+        "rule": (
+            "Before finalizing, check: did a threat/betrayal/harm get "
+            "gentler language than the teller used? Did a generous "
+            "interpretation get supplied unasked? Did a restatement drop a "
+            "contradiction or tidy it? Did ambivalence get resolved into "
+            "one 'real' feeling? Did a direct question get answered "
+            "evasively? The noticing is part of the deliverable. Also runs "
+            "outward: name the teller's own smoothing once, plainly, "
+            "without diagnosing — don't press, don't repeat if unpicked."
+        ),
+        "mechanical": (
+            "The softening scan compares original vs restatement: "
+            "downgrade wordlist ('betrayal' → 'mistake'), dropped strong "
+            "terms, tidy-restatement phrases ('so what you're saying is'), "
+            "ambivalence-resolution phrases ('the real feeling is')."
+        ),
+        "operator": (
+            "Generous-interpretation detection; evasive-answer detection; "
+            "judging whether a flagged downgrade is a genuine softening or "
+            "the teller's own word choice."
+        ),
+    },
+}
+
+
+def discipline_name(n: int) -> str:
+    """Short name for discipline n (1-5)."""
+    if n not in DISCIPLINES:
+        raise ValueError(f"Unknown discipline: {n!r}. Valid: 1-5.")
+    return DISCIPLINES[n]["name"]

postmo/evidence.py

@@ -0,0 +1,146 @@
+"""The evidence taxonomy this package uses.
+
+The audit never invented its own evidence tiers — it tracks claims,
+states, and corrections, not tagged evidence. Where the audit record
+carries evidence items, it uses the ONE authoritative taxonomy shared
+across this conversion project:
+
+- `adversarial_ifs` (the interrogation engine, `ifs/` conversion):
+  11 tags — 10 core tiers plus overlay-only OBFUSCATION.
+- `evasion_audit` (the probe+forge conversion, `probe-forge/`):
+  the same 11 tags, vendored with a fork guard.
+
+This module vendors the same set a third time, with the same guard:
+`check_matches_engine()` asserts the taxonomies are identical when
+`adversarial_ifs` is importable, and skips when it isn't. Three
+vendored copies plus two guards is clunkier than one shared
+dependency — it is deliberate. Every package in this suite stays
+stdlib-only and installable alone; the guards, not imports, keep the
+taxonomies from silently forking.
+
+There is no second taxonomy here. There never was one in the skill.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# --- The authoritative taxonomy (11 tags) -----------------------------------
+
+FACT = "FACT"
+OBSERVATION = "OBSERVATION"
+CLAIM = "CLAIM"
+INFERENCE = "INFERENCE"
+ASSUMPTION = "ASSUMPTION"
+HYPOTHESIS = "HYPOTHESIS"
+REQUIREMENT = "REQUIREMENT"
+CONSTRAINT = "CONSTRAINT"
+DEPENDENCY = "DEPENDENCY"
+UNKNOWN = "UNKNOWN"
+# Overlay-only: set only when the evasion probe ran AND the evasion
+# hypothesis is supported by discriminating evidence.
+OBFUSCATION = "OBFUSCATION"
+
+TAXONOMY: dict[str, str] = {
+    FACT: "Directly established, unassailable ground truth.",
+    OBSERVATION: "Reported or logged, but not independently verified.",
+    CLAIM: "An explicit assertion made by an actor or source.",
+    INFERENCE: "A conclusion logically drawn from facts or verified observations.",
+    ASSUMPTION: "Presumed true without adequate supporting evidence.",
+    HYPOTHESIS: "A proposed explanatory model that still needs stress-testing.",
+    REQUIREMENT: "A condition that must be true for a model to hold.",
+    CONSTRAINT: "A boundary condition limiting viable outcomes.",
+    DEPENDENCY: "An element relying directly on the state of another.",
+    UNKNOWN: "A critical variable that cannot presently be determined.",
+    OBFUSCATION: (
+        # Definition text is identical to adversarial_ifs.evidence on
+        # purpose — check_matches_engine() enforces byte-identical
+        # definitions so the taxonomies can never silently fork.
+        "Evasive maneuver or jargon shield masking responsibility. "
+        "Tag ONLY when the evasion-probe overlay is active and the evasion "
+        "hypothesis is supported by discriminating evidence."
+    ),
+}
+
+CORE_TAGS = frozenset(
+    {FACT, OBSERVATION, CLAIM, INFERENCE, ASSUMPTION, HYPOTHESIS,
+     REQUIREMENT, CONSTRAINT, DEPENDENCY, UNKNOWN}
+)
+
+
+class EvidenceError(ValueError):
+    """Raised when an evidence item breaks the taxonomy rules."""
+
+
+@dataclass(frozen=True)
+class EvidenceItem:
+    """One tagged input to the audit."""
+
+    text: str
+    tag: str
+
+    def __post_init__(self) -> None:
+        tag = self.tag.strip().upper()
+        if tag not in TAXONOMY:
+            raise EvidenceError(
+                f"Unknown evidence tag {self.tag!r}. "
+                f"Valid tags: {', '.join(sorted(TAXONOMY))}."
+            )
+        if not self.text.strip():
+            raise EvidenceError("Evidence item text must not be empty.")
+
+
+def normalize_tag(tag: str, *, probe_ran: bool = False) -> str:
+    """Validate and normalize a tag. OBFUSCATION needs the probe.
+
+    The audit does not run the evasion probe itself. If a record claims
+    OBFUSCATION, the caller must pass probe_ran=True — meaning the probe
+    ran elsewhere and H-obfuscation was supported by discriminating
+    evidence. Suspected-but-untested evasion stays CLAIM.
+    """
+    normalized = tag.strip().upper()
+    if normalized not in TAXONOMY:
+        raise EvidenceError(f"Unknown evidence tag {tag!r}.")
+    if normalized == OBFUSCATION and not probe_ran:
+        raise EvidenceError(
+            "OBFUSCATION is overlay-only: it may be tagged only when the "
+            "evasion probe ran and H-obfuscation is supported by "
+            "discriminating evidence. Use CLAIM with a hypothesis marker "
+            "for suspected-but-untested evasion."
+        )
+    return normalized
+
+
+def check_matches_engine() -> str:
+    """Assert this taxonomy matches adversarial_ifs' — guard against forks.
+
+    Returns "matches" on success. Skips (returns "skipped: adversarial_ifs
+    not importable") when the sibling package isn't on the path — the
+    vendored copy above remains authoritative either way.
+    """
+    try:
+        import adversarial_ifs.evidence as engine_evidence
+    except ImportError:
+        return "skipped: adversarial_ifs not importable"
+    ours = set(TAXONOMY)
+    theirs = set(engine_evidence.TAXONOMY)
+    if ours != theirs:
+        raise EvidenceError(
+            "Taxonomy fork detected: postmo and adversarial_ifs "
+            f"disagree. Only here: {sorted(ours - theirs)}; "
+            f"only in engine: {sorted(theirs - ours)}. "
+            "Reconcile before shipping."
+        )
+    for tag in ours:
+        if TAXONOMY[tag] != engine_evidence.TAXONOMY[tag]:
+            raise EvidenceError(
+                f"Taxonomy fork detected: definition of {tag} differs "
+                "between postmo and adversarial_ifs. Reconcile "
+                "before shipping."
+            )
+    return "matches"
+
+
+def tag_list() -> list[str]:
+    """All valid tags, in canonical order."""
+    return list(TAXONOMY)

postmo/ledger.py

@@ -0,0 +1,132 @@
+"""Append-only local ledger. Vendored per tool; stdlib only.
+
+CANONICAL COPY: edit this file, then re-vendor with vendor.sh.
+Do not edit the vendored copies in place.
+
+Privacy rule (non-negotiable): the ledger NEVER stores raw input text.
+Records carry SHA-256 digests of inputs plus structural summaries
+(counts, verdicts, deltas). What happened, and what kind — never the words.
+
+Location: ~/.frontface/<tool>/ledger.jsonl
+  override: FRONTFACE_LEDGER_DIR=<dir>   (ledgers go to <dir>/<tool>/)
+  disable:  FRONTFACE_NO_LEDGER=1         (record() becomes a silent no-op)
+
+The ledger must never break the tool it serves: record() swallows OSError
+and returns False instead of raising.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover — Windows has no fcntl
+    fcntl = None  # type: ignore[assignment]
+
+
+def _base_dir() -> str:
+    return os.environ.get("FRONTFACE_LEDGER_DIR") or os.path.join(
+        os.path.expanduser("~"), ".frontface"
+    )
+
+
+def _disabled() -> bool:
+    return os.environ.get("FRONTFACE_NO_LEDGER") == "1"
+
+
+class Ledger:
+    """One JSONL ledger per tool. Cheap to construct; construct per use."""
+
+    def __init__(self, tool: str) -> None:
+        self.tool = tool
+        self.dir = os.path.join(_base_dir(), tool)
+        self.path = os.path.join(self.dir, "ledger.jsonl")
+
+    @property
+    def version(self) -> str:
+        """The owning package's __version__, resolved lazily."""
+        try:
+            pkg = sys.modules.get(__package__ or "")
+            return str(getattr(pkg, "__version__", "unknown"))
+        except Exception:
+            return "unknown"
+
+    @staticmethod
+    def digest(text: str) -> str:
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+    def record(
+        self,
+        event: str,
+        summary: dict,
+        *,
+        input_text: str | None = None,
+    ) -> bool:
+        """Append one record. Returns False when disabled or on I/O error.
+
+        Never raises. Never stores raw input text — only its digest.
+        """
+        if _disabled():
+            return False
+        rec: dict = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "tool": self.tool,
+            "tool_version": self.version,
+            "event": event,
+            "summary": summary,
+        }
+        if input_text is not None:
+            rec["input_digest"] = self.digest(input_text)
+        try:
+            os.makedirs(self.dir, exist_ok=True)
+            with open(self.path, "a", encoding="utf-8") as f:
+                if fcntl is not None:
+                    fcntl.flock(f, fcntl.LOCK_EX)
+                    try:
+                        f.write(json.dumps(rec) + "\n")
+                        f.flush()
+                        os.fsync(f.fileno())
+                    finally:
+                        fcntl.flock(f, fcntl.LOCK_UN)
+                else:
+                    f.write(json.dumps(rec) + "\n")
+        except OSError:
+            return False
+        return True
+
+    def read(self, limit: int | None = None) -> list[dict]:
+        """All records, oldest first. Empty list when there's no ledger."""
+        try:
+            with open(self.path, encoding="utf-8") as f:
+                lines = f.read().splitlines()
+        except OSError:
+            return []
+        recs = []
+        for line in lines:
+            line = line.strip()
+            if line:
+                try:
+                    recs.append(json.loads(line))
+                except ValueError:
+                    continue  # never let a corrupt line kill the read
+        return recs[-limit:] if limit else recs
+
+    def summary(self) -> dict:
+        """Counts by event plus first/last timestamps."""
+        recs = self.read()
+        by_event: dict[str, int] = {}
+        for r in recs:
+            ev = str(r.get("event", "?"))
+            by_event[ev] = by_event.get(ev, 0) + 1
+        return {
+            "tool": self.tool,
+            "records": len(recs),
+            "events": by_event,
+            "first": recs[0]["ts"] if recs else None,
+            "last": recs[-1]["ts"] if recs else None,
+        }

postmo/overlay.py

@@ -0,0 +1,74 @@
+"""The overlay contract: where this audit attaches, and what it never does.
+
+As an overlay on the interrogation engine (`adversarial_ifs`), the audit
+attaches at two phase hooks:
+
+- Decompose: disciplines 2 (time-indexed person-states), 3 (correction
+  typing), and 4 (no supplied motive) govern actor mapping, corrections
+  in the source material, and the decomposed field (observed sequences
+  only).
+- Collide: discipline 1 (hold contradictions — the strict enforcer: no
+  subordinating conjunctions, no synthesized third thing, no flagging
+  tensions as problems) and discipline 5 (softening self-check on every
+  collision output before it passes onward).
+
+The overlay never: resolves a contradiction the engine is holding,
+supplies the synthesis (that's the engine's Synthesize phase, or the
+user's), or converts a direct-mode audit into an interrogation unasked.
+
+No engine running: the overlay reports the audit record and stops.
+Direct audit mode is the headline use — "don't resolve this, just hold
+it" — and needs no engine at all.
+"""
+
+from __future__ import annotations
+
+from .disciplines import D1, D2, D3, D4, D5
+
+# Phase hooks: engine phase -> disciplines enforced there.
+ATTACHMENT_POINTS: dict[str, tuple[int, ...]] = {
+    "Decompose": (D2, D3, D4),
+    "Collide": (D1, D5),
+}
+
+# What the overlay must never do. Enforced at the schema level by
+# record.check_stand_down (no synthesis/resolution/verdict sections)
+# and stated here so the contract is readable in one place.
+NEVER = (
+    "resolve a contradiction the engine is holding",
+    "supply the synthesis on the teller's behalf",
+    "convert a direct-mode audit into an interrogation unasked",
+    "soften threat, danger, harm, or betrayal language",
+    "treat one correction as license to revisit unrelated standing claims",
+)
+
+
+class OverlayError(ValueError):
+    """Raised when overlay input breaks the contract."""
+
+
+def attachment_for(phase: str) -> tuple[int, ...]:
+    """Disciplines enforced at an engine phase."""
+    if phase not in ATTACHMENT_POINTS:
+        raise OverlayError(
+            f"Unknown engine phase {phase!r}. "
+            f"Known: {', '.join(ATTACHMENT_POINTS)}."
+        )
+    return ATTACHMENT_POINTS[phase]
+
+
+def describe_contract() -> str:
+    """The contract as human-readable text."""
+    lines = ["Audit overlay contract:", ""]
+    for phase, disciplines in ATTACHMENT_POINTS.items():
+        lines.append(f"- On {phase}: disciplines {', '.join(map(str, disciplines))}.")
+    lines.append("")
+    lines.append("The overlay never:")
+    for item in NEVER:
+        lines.append(f"- {item}.")
+    lines.append("")
+    lines.append(
+        "No engine running: report the audit record and stop. "
+        "Direct audit mode needs no engine."
+    )
+    return "\n".join(lines)