procheiron 0.1.0__tar.gz

procheiron-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.bak
+.procheiron/locks/
+.procheiron/backups/
+*.log
+.DS_Store

procheiron-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/) v2.1.
+
+Be respectful, assume good faith, and focus on the work. Harassment or abusive behavior is not tolerated.
+Report concerns by opening a confidential issue or contacting the maintainers.
+
+The full Contributor Covenant text applies; see https://www.contributor-covenant.org/version/2/1/code_of_conduct/.

procheiron-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to Procheiron
+
+Procheiron is a spec + reference implementation for governed agent memory. Contributions are welcome,
+with one rule that comes from the project's own subject matter: **claims trail proofs.**
+
+## Ground rules
+
+1. **Every behavioral claim must be backed by the conformance suite.** If you change governance behavior,
+   add or update a fixture in `conformance/` and make `run_conformance.py` green. A PR that changes
+   behavior without a fixture will be asked for one.
+2. **Zero runtime dependencies.** Anything a deployment runs at runtime must be standard-library Python.
+   Dev/CI-only tools (jsonschema, opa) are fine but must never be required to run the validator, init, or
+   the minimal adopter.
+3. **No secrets, ever.** No real credentials, tokens, identities, or private deployment content in any
+   fixture, example, or test. Secret-*shaped* strings used to test detection must be generated at runtime,
+   not committed (see `run_conformance.py`).
+4. **Portable Core, specific Profile.** Keep deployment-specific detail (paths, identities, ladder/gate
+   tables, executor bindings) in profiles/examples — not in the normative spec. See `spec/boundary.md`.
+5. **Number honestly.** This is v0.1. v1.0 is earned only when a second *real* deployment passes
+   conformance — not by a fixture pass, a single deployment, or authority approval alone.
+
+## How to propose a change
+
+- Open an issue describing the behavior and why.
+- For spec changes, edit `spec/` and update `conformance.md` (the MUST-list) together.
+- Run `python3 conformance/run_conformance.py` and include the output in your PR.
+
+## What's most wanted right now
+
+See the Roadmap in `README.md` — the standalone, `--root`-relative MCP server is the top item.

procheiron-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Procheiron contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

procheiron-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: procheiron
+Version: 0.1.0
+Summary: Governance and provenance layer for agent memory.
+License: MIT License
+        
+        Copyright (c) 2026 Procheiron contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Procheiron
+
+**A governance and provenance layer for agent memory.** Not a memory engine — the trust layer that
+sits on top of one.
+
+Memory engines (supermemory, mempalace, agentmemory, a vector DB, or plain files) answer *"what does my
+agent remember?"* Procheiron answers a different question: **"can a *different* agent trust this memory,
+and prove who wrote it, who reviewed it, and who authorized it?"** It is built for the case a single-agent
+memory store ignores — **multiple agents sharing one governed source of truth.**
+
+Status: **v0.1 draft, pre-release.** Conformance passes at fixture level (a second, fully fictional
+deployment validates against the same Core). Honest scope discipline: nothing here claims more than the
+conformance suite proves.
+
+## Why this exists
+
+Give an agent keys and it will use them. Give several agents a shared memory and, without governance, any
+one of them can write a "fact" the others will trust — no record of who, no independent review, no way to
+supersede it cleanly. Procheiron makes the trustworthy path the easy one:
+
+- **Provenance-first lifecycle** — every memory is `draft → candidate → validated → active → superseded`.
+  An `active` (trusted) record requires independent review by an actor that is *not* its author.
+- **Authority, not vibes** — who may promote, review, or authorize is policy, checked by a validator and a
+  policy engine, not a prompt asking nicely.
+- **Provable, replayable** — a conformance suite checks that a deployment obeys the spec; a fictional
+  reference deployment (`conformance/generic-vault/`) proves the same Core governs a vault it has never
+  seen.
+
+## What's in this repo
+
+| Path | What it is |
+|---|---|
+| `spec/` | The v0.1 specification: `governance.md`, `memory-commons.md`, `control-plane.md`, the normative `conformance.md` MUST-list, and the Core/Profile `boundary.md`. |
+| `conformance/` | `run_conformance.py` + fixtures. `generic-vault/` is a complete fictional deployment ("Meridian Atelier"); `minimal-vault/` is the 5-file minimal adopter. Run it to prove conformance. |
+| `examples/minimal-adopter/` | The smallest compliant deployment — a memory commons with provenance + independent review, no heavyweight governance ladder. |
+| `init/` | `procheiron_init.py` scaffolds a new deployment; `PORTING_GUIDE.md` is the step-by-step. |
+
+## Quick start
+
+```bash
+# Install (zero runtime dependencies — stdlib-only Python):
+pipx install procheiron          # or: pip install procheiron
+
+# Scaffold a governed memory commons and validate it:
+procheiron init ./my-commons
+procheiron validate ./my-commons
+```
+
+From a source checkout (no install required):
+
+```bash
+# Prove the spec holds against the bundled fixtures:
+python3 conformance/run_conformance.py
+
+# Scaffold via the init script directly:
+python3 init/procheiron_init.py --root ./my-commons
+```
+
+## Design choices worth knowing
+
+- **Zero runtime dependencies.** Every tool a live deployment runs is standard-library Python. (`jsonschema`,
+  `opa` etc. are used only for development/CI cross-checks, never required at runtime.) Adopt it without
+  taking on a dependency tree.
+- **Bring your own memory engine.** Procheiron governs records and their lifecycle; it does **not** do
+  embeddings or retrieval and never will (that is the engine's job). Point it at any store.
+- **Core vs Profile.** The spec is portable Core. Deployment-specific bindings (identities, paths, a git
+  preservation executor, a full L0–L9 authority ladder) live in a *profile* — see `boundary.md`.
+
+## Not in scope (by design)
+
+No vector/retrieval engine. No recall benchmarks — that is the memory engine's axis, not ours. No claim of
+"production-replicable" until a second *real* deployment passes conformance (fixture-level proof is what
+exists today, and the README says exactly that).
+
+## Roadmap (next, post first-deployment feedback)
+
+1. **Standalone MCP server** — `memory.search/get/propose/promote` + `boot_context`, the "any agent has the
+   context on hand" integration. (A working version exists but is currently coupled to its origin
+   deployment's layout; the port to a `--root`-relative standalone server is the top item.)
+2. ~~PyPI / `pipx` packaging and a one-command `procheiron init`.~~ **Shipped in v0.1** — `pip install procheiron`, `procheiron init`, `procheiron validate`.
+3. A reference integration: Procheiron governing a third-party memory engine end to end.
+
+## License
+
+MIT — see `LICENSE`.

procheiron-0.1.0/README.md

@@ -0,0 +1,85 @@
+# Procheiron
+
+**A governance and provenance layer for agent memory.** Not a memory engine — the trust layer that
+sits on top of one.
+
+Memory engines (supermemory, mempalace, agentmemory, a vector DB, or plain files) answer *"what does my
+agent remember?"* Procheiron answers a different question: **"can a *different* agent trust this memory,
+and prove who wrote it, who reviewed it, and who authorized it?"** It is built for the case a single-agent
+memory store ignores — **multiple agents sharing one governed source of truth.**
+
+Status: **v0.1 draft, pre-release.** Conformance passes at fixture level (a second, fully fictional
+deployment validates against the same Core). Honest scope discipline: nothing here claims more than the
+conformance suite proves.
+
+## Why this exists
+
+Give an agent keys and it will use them. Give several agents a shared memory and, without governance, any
+one of them can write a "fact" the others will trust — no record of who, no independent review, no way to
+supersede it cleanly. Procheiron makes the trustworthy path the easy one:
+
+- **Provenance-first lifecycle** — every memory is `draft → candidate → validated → active → superseded`.
+  An `active` (trusted) record requires independent review by an actor that is *not* its author.
+- **Authority, not vibes** — who may promote, review, or authorize is policy, checked by a validator and a
+  policy engine, not a prompt asking nicely.
+- **Provable, replayable** — a conformance suite checks that a deployment obeys the spec; a fictional
+  reference deployment (`conformance/generic-vault/`) proves the same Core governs a vault it has never
+  seen.
+
+## What's in this repo
+
+| Path | What it is |
+|---|---|
+| `spec/` | The v0.1 specification: `governance.md`, `memory-commons.md`, `control-plane.md`, the normative `conformance.md` MUST-list, and the Core/Profile `boundary.md`. |
+| `conformance/` | `run_conformance.py` + fixtures. `generic-vault/` is a complete fictional deployment ("Meridian Atelier"); `minimal-vault/` is the 5-file minimal adopter. Run it to prove conformance. |
+| `examples/minimal-adopter/` | The smallest compliant deployment — a memory commons with provenance + independent review, no heavyweight governance ladder. |
+| `init/` | `procheiron_init.py` scaffolds a new deployment; `PORTING_GUIDE.md` is the step-by-step. |
+
+## Quick start
+
+```bash
+# Install (zero runtime dependencies — stdlib-only Python):
+pipx install procheiron          # or: pip install procheiron
+
+# Scaffold a governed memory commons and validate it:
+procheiron init ./my-commons
+procheiron validate ./my-commons
+```
+
+From a source checkout (no install required):
+
+```bash
+# Prove the spec holds against the bundled fixtures:
+python3 conformance/run_conformance.py
+
+# Scaffold via the init script directly:
+python3 init/procheiron_init.py --root ./my-commons
+```
+
+## Design choices worth knowing
+
+- **Zero runtime dependencies.** Every tool a live deployment runs is standard-library Python. (`jsonschema`,
+  `opa` etc. are used only for development/CI cross-checks, never required at runtime.) Adopt it without
+  taking on a dependency tree.
+- **Bring your own memory engine.** Procheiron governs records and their lifecycle; it does **not** do
+  embeddings or retrieval and never will (that is the engine's job). Point it at any store.
+- **Core vs Profile.** The spec is portable Core. Deployment-specific bindings (identities, paths, a git
+  preservation executor, a full L0–L9 authority ladder) live in a *profile* — see `boundary.md`.
+
+## Not in scope (by design)
+
+No vector/retrieval engine. No recall benchmarks — that is the memory engine's axis, not ours. No claim of
+"production-replicable" until a second *real* deployment passes conformance (fixture-level proof is what
+exists today, and the README says exactly that).
+
+## Roadmap (next, post first-deployment feedback)
+
+1. **Standalone MCP server** — `memory.search/get/propose/promote` + `boot_context`, the "any agent has the
+   context on hand" integration. (A working version exists but is currently coupled to its origin
+   deployment's layout; the port to a `--root`-relative standalone server is the top item.)
+2. ~~PyPI / `pipx` packaging and a one-command `procheiron init`.~~ **Shipped in v0.1** — `pip install procheiron`, `procheiron init`, `procheiron validate`.
+3. A reference integration: Procheiron governing a third-party memory engine end to end.
+
+## License
+
+MIT — see `LICENSE`.

procheiron-0.1.0/conformance/generic-vault/.procheiron/config.yaml

@@ -0,0 +1,29 @@
+version: 0.1
+profile: meridian
+root: .
+paths:
+  console: console
+  memory: memory
+  sources: sources
+  wiki: knowledge
+  outputs: outputs
+  adapters: adapters
+  legacy_governance: studio
+  workspace: workspace
+  runtime_root: runtime/procheiron
+  runtime_state: runtime/state/STATE.json
+  scripts: scripts
+policy_defaults:
+  local_first: true
+  human_visible: true
+  raw_sources_immutable: true
+  derived_memory_rebuildable: true
+  provenance_required: true
+  temporal_by_default: true
+  no_runtime_lock_in: true
+  no_external_actions_by_default: true
+  no_hooks_phase_1_2: true
+  no_cron_changes_phase_1_2: true
+  no_package_installs_phase_1_2: true
+  agents_may_propose_not_promote: true
+  secrets_allowed: false

procheiron-0.1.0/conformance/generic-vault/.procheiron/lib/procheiron_lock.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Single-writer advisory lock for the Procheiron memory indexes (roadmap 3.6).
+
+STAGED ARTIFACT — installs to .procheiron/lib/procheiron_lock.py under the
+Phase-3 adoption authorization, shared by memory_promote.py and memory_propose.py
+so there is one lock implementation, no drift. Stdlib-only.
+
+Discipline: O_CREAT|O_EXCL create (no auto-steal), age-surfaced contention,
+unlink on exit (including SystemExit). Extracted verbatim-in-behavior from the
+Lock already living in the live memory_promote.py.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import os
+from pathlib import Path
+from typing import Any
+
+
+class LockHeld(SystemExit):
+    """Raised (as SystemExit, so a CLI exits cleanly) when the lock is held."""
+
+
+class Lock:
+    def __init__(self, root: Path) -> None:
+        lock_dir = Path(root) / ".procheiron" / "locks"
+        lock_dir.mkdir(parents=True, exist_ok=True)
+        self.path = lock_dir / "memory_index.lock"
+
+    def __enter__(self) -> "Lock":
+        try:
+            fd = os.open(str(self.path), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            age = dt.datetime.now().timestamp() - self.path.stat().st_mtime
+            raise LockHeld(
+                f"memory index lock held ({self.path}, {int(age)}s old); "
+                "retry or remove a stale lock manually"
+            )
+        os.write(fd, f"{os.getpid()} {dt.datetime.now(dt.timezone.utc).isoformat()}\n".encode())
+        os.close(fd)
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        try:
+            self.path.unlink()
+        except FileNotFoundError:
+            pass

procheiron-0.1.0/conformance/generic-vault/.procheiron/lib/procheiron_paths.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Source-path normalization for Procheiron memory records.
+
+Converts machine-absolute provenance paths into self-describing, portable
+forms so records survive a deployment move (the data-plane weld from the
+2026-06-10/11 audits):
+
+- a path under the deployment root becomes root-relative
+- a path under any absolute `paths.<key>` from config.yaml becomes
+  `{paths.<key>}/<rest>` (longest prefix wins)
+- any other absolute path is returned unchanged and reported by the caller
+
+Used by memory_propose.py (normalize at write time) and migrate_records.py
+(repair existing records). Stdlib-only.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Optional, Tuple
+
+
+def normalize_source_path(cfg: Any, raw: str) -> Tuple[str, bool]:
+    """Return (normalized_path, changed). Non-absolute input passes through."""
+    if not raw or not raw.startswith('/'):
+        return raw, False
+    # Collapse `..`/`.` segments BEFORE prefix matching so a path like
+    # `/v/memory/../secret/x` does not falsely tokenize under {paths.memory}
+    # (review finding L-4). normpath is lexical only — it never touches disk
+    # or resolves symlinks, so it cannot leak filesystem state.
+    raw = os.path.normpath(raw)
+    candidate = Path(raw)
+    best_key: Optional[str] = None
+    best_len = -1
+    for key, value in cfg.paths.items():
+        base = Path(str(value))
+        if not base.is_absolute():
+            continue
+        try:
+            rest = candidate.relative_to(base)
+        except ValueError:
+            continue
+        if len(str(base)) > best_len:
+            best_key, best_len = key, len(str(base))
+            best_rest = rest
+    root = Path(str(cfg.root))
+    try:
+        root_rest = candidate.relative_to(root)
+        root_len = len(str(root))
+    except ValueError:
+        root_rest, root_len = None, -1
+
+    if root_rest is not None and root_len >= best_len:
+        return root_rest.as_posix(), True
+    if best_key is not None:
+        rest_str = best_rest.as_posix()
+        if rest_str == '.':
+            return '{paths.%s}' % best_key, True
+        return '{paths.%s}/%s' % (best_key, rest_str), True
+    return raw, False

procheiron-0.1.0/conformance/generic-vault/.procheiron/lib/procheiron_patterns.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Shared Procheiron secret-pattern registry.
+
+Single source of truth for secret detection across the validator
+(validate_procheiron2.py), the candidate-append helper (memory_propose.py),
+and the promotion gate (memory_promote.py). Reunified 2026-06-11 per the
+A-to-Z audit finding that the v2 validator had regressed to 3 patterns
+(AKIA dropped) while memory_propose carried 11 unshared.
+
+Stdlib-only. Importing this module must never require third-party packages.
+"""
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import List, Tuple
+
+# (label, compiled pattern). Labels are stable identifiers used in reports.
+SECRET_PATTERNS: List[Tuple[str, "re.Pattern[str]"]] = [
+    ("openai_style_key", re.compile(r"\bsk-[A-Za-z0-9_\-]{16,}\b")),
+    ("stripe_key", re.compile(r"\bsk_(live|test)_[A-Za-z0-9]{16,}\b")),
+    ("github_token", re.compile(r"\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b")),
+    ("github_fine_grained", re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b")),
+    ("google_api_key", re.compile(r"\bAIza[0-9A-Za-z_\-]{30,}\b")),
+    ("slack_token", re.compile(r"\bxox[baprs]-[A-Za-z0-9\-]{10,}\b")),
+    ("aws_access_key_id", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("jwt", re.compile(r"\beyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.")),
+    ("bearer_token", re.compile(r"(?i)\bbearer\s+[A-Za-z0-9\-_\.=]{16,}")),
+    (
+        "credential_assignment",
+        re.compile(r"(?i)[\"']?(password|passwd|api[_-]?key|secret|token)[\"']?\s*[:=]\s*[\"']?\S{12,}"),
+    ),
+    ("private_key_block", re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----")),
+]
+
+
+_ZERO_WIDTH = {"​", "‌", "‍", "⁠", ""}
+
+
+def normalize_for_scan(text: str) -> str:
+    """NFKC-normalize and strip zero-width/format chars before secret scanning.
+
+    Defeats the common evasions: a zero-width space inside a key, a fullwidth
+    colon in `password：`, an NBSP in a token. Without this, the regexes run on
+    the raw bytes and a single invisible character hides a live credential
+    (review finding L-1). We strip Unicode Cf (format) chars and the explicit
+    zero-width set, then NFKC-fold width/compatibility variants.
+    """
+    if not text:
+        return ""
+    out = []
+    for ch in text:
+        if ch in _ZERO_WIDTH:
+            continue
+        if unicodedata.category(ch) == "Cf":
+            continue
+        out.append(ch)
+    return unicodedata.normalize("NFKC", "".join(out))
+
+
+def scan_text(text: str) -> List[Tuple[int, str]]:
+    """Return (line_number, label) findings for every secret-pattern hit.
+
+    Each line is scanned both raw and normalized, so an evaded credential is
+    still caught while line numbers stay meaningful.
+    """
+    findings: List[Tuple[int, str]] = []
+    for lineno, line in enumerate(text.splitlines(), 1):
+        norm = normalize_for_scan(line)
+        for label, pattern in SECRET_PATTERNS:
+            if pattern.search(line) or (norm != line and pattern.search(norm)):
+                findings.append((lineno, label))
+    return findings
+
+
+def first_match_label(text: str) -> str | None:
+    """Return the label of the first matching pattern, or None.
+
+    Scans both the raw and normalized forms so zero-width / homoglyph evasions
+    do not slip a live secret past the guard.
+    """
+    raw = text or ""
+    norm = normalize_for_scan(raw)
+    for label, pattern in SECRET_PATTERNS:
+        if pattern.search(raw) or (norm != raw and pattern.search(norm)):
+            return label
+    return None