goldenreq 0.3.0__py3-none-any.whl

goldenreq/__init__.py

@@ -0,0 +1,30 @@
+"""goldenreq — the ACCEPTANCE GATE for goldenization.
+
+THE LAW (gauge ≠ handler). A *gauge* is an internal self-assessment: the
+bandit's 2×🏆 on a chain, a rulecatcher candidate, a forged template, a
+personapack grade claim. A gauge may detect quality but it may NEVER certify
+itself. Promotion to golden/adopted/canon happens only through a *handler* — an
+external acceptance authority. This package is that gate.
+
+  - `queue.file_request(...)` — a gauge FILES a request carrying its receipts
+    (evidence). That is the only move a gauge gets. The request sits pending.
+  - `verdict.accept / verdict.reject` — a handler rules. Only `accept` fires the
+    promotion effect (`effects.dispatch`). `reject` carries a reason.
+
+Requests carry receipts; verdicts are the seed corpus for the learned acceptance
+model that will one day staff this gate; rejections (with reasons) are its hard
+negatives. The verdict record mirrors base/acceptance's `Verdict` schema so the
+corpus is drop-in for that reader (field mapping: see `verdict.py`).
+"""
+from __future__ import annotations
+
+__version__ = "0.3.0"
+
+from .queue import KINDS, file_request, list_pending, get_request
+from .verdict import accept, reject, list_verdicts
+from . import effects
+
+__all__ = [
+    "KINDS", "file_request", "list_pending", "get_request",
+    "accept", "reject", "list_verdicts", "effects", "__version__",
+]

goldenreq/cli.py

@@ -0,0 +1,60 @@
+"""cli.py — `goldenreq list | accept | reject` (argparse, stdlib only)."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .queue import list_pending
+from .verdict import accept, reject
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="goldenreq",
+                                description="the acceptance gate for goldenization — nothing self-promotes")
+    p.add_argument("--queue", default=None, help="queue JSONL path ($GOLDENREQ_QUEUE_PATH)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    lp = sub.add_parser("list", help="list pending requests (the handler's inbox)")
+    lp.add_argument("--json", action="store_true", help="emit raw JSON lines")
+
+    ap = sub.add_parser("accept", help="accept a request → fire its promotion effect")
+    ap.add_argument("request_id")
+    ap.add_argument("--by", required=True, help="ruling actor (human:<who> / model:<id>)")
+    ap.add_argument("--reason", default="")
+
+    rp = sub.add_parser("reject", help="reject a request (reason = hard negative)")
+    rp.add_argument("request_id")
+    rp.add_argument("--by", required=True, help="ruling actor (human:<who> / model:<id>)")
+    rp.add_argument("--reason", required=True)
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "list":
+        pending = list_pending(args.queue)
+        if args.json:
+            for r in pending:
+                print(json.dumps(r, sort_keys=True))
+        elif not pending:
+            print("no pending requests")
+        else:
+            for r in pending:
+                print(f"{r['request_id']}  {r['kind']:<16}  {r['candidate_id']}  "
+                      f"→ {r['requested_promotion']}  (by {r['requester']}, "
+                      f"{len(r.get('evidence', []))} receipt(s))")
+        return 0
+
+    try:
+        if args.cmd == "accept":
+            v = accept(args.request_id, args.by, args.reason, queue_path=args.queue)
+        else:
+            v = reject(args.request_id, args.by, args.reason, queue_path=args.queue)
+    except (ValueError, FileNotFoundError, NotImplementedError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(json.dumps(v, sort_keys=True, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

goldenreq/effects.py

@@ -0,0 +1,105 @@
+"""effects.py — the promotion effects, dispatched ONLY on an accepted verdict.
+
+`dispatch` routes an accepted request to its effect by `kind`. An effect is the
+thing the gauge was NOT allowed to do itself; here it runs because a handler
+accepted. Each returns an `outcome` dict that verdict.py stores in the record.
+
+Honesty rule: two effects are real (they have a testable local target), two are
+stubs (they'd need cross-package wiring we cannot exercise here). The stubs
+raise `NotImplementedError` and point at the exact upstream call to make — we do
+NOT fake an integration we can't test.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+# the personapack activation_grade ladder, BEST → WORST.
+# Mirror of personapack.entry.GRADES (kept as a literal so goldenreq stays
+# dependency-free; a drift here is caught by the pack-grade-bump test).
+PACK_GRADES: tuple[str, ...] = ("tested-with-receipt", "proven-in-forge", "seed")
+
+
+def dispatch(request: dict, *, by: str, **kwargs) -> dict:
+    """Route an ACCEPTED request to its promotion effect. Returns the outcome dict."""
+    kind = request.get("kind")
+    if kind == "chain-golden":
+        return mark_chain_golden(request, by=by, **kwargs)
+    if kind == "pack-grade-bump":
+        new_grade = bump_pack_grade(request.get("requested_promotion") or _current_from(request))
+        return {"effect": "pack-grade-bump", "new_grade": new_grade,
+                "note": "pure result — personapack applies it to the PackEntry"}
+    if kind == "rule-adopt":
+        return adopt_rule(request, by=by, **kwargs)
+    if kind == "template-promote":
+        return promote_template(request, by=by, **kwargs)
+    raise ValueError(f"no effect for kind {request.get('kind')!r}")
+
+
+def _current_from(request: dict) -> str:
+    # if requested_promotion wasn't a grade, fall back to the weakest rung
+    return "seed"
+
+
+# ── chain-golden: append an ACCEPTED-BY marker into the GBA KB note ──────────
+def mark_chain_golden(request: dict, *, by: str, **_) -> dict:
+    """Write the golden marker into the GBA KB.
+
+    `candidate_id` is the path to the graded KB note (a `kb/<topic>.md`, headed
+    with a `glyphs:` grade line — see chainaios bandit.kb_instructions). We
+    APPEND an ACCEPTED-BY line; we NEVER rewrite the agent's own notes. The
+    marker is what turns "the gauge claims 🏆🏆" into "a handler certified it
+    golden" — the thing self-folding used to do without authority.
+    """
+    note = Path(request["candidate_id"])
+    if not note.exists():
+        raise FileNotFoundError(f"KB note not found: {note}")
+    marker = (f"\nACCEPTED-BY: {by} — goldenized on request {request['request_id']} "
+              f"(promotion: {request.get('requested_promotion')}); "
+              f"evidence: {', '.join(request.get('evidence', [])) or 'none'}. 🏆🏆 → golden\n")
+    with open(note, "a", encoding="utf-8") as f:
+        f.write(marker)
+    return {"effect": "chain-golden", "kb_note": str(note), "marker": marker.strip()}
+
+
+# ── pack-grade-bump: a PURE function personapack applies itself ──────────────
+def bump_pack_grade(current_grade: str) -> str:
+    """Return the next-higher personapack `activation_grade`, or the same grade
+    if already at the top. PURE — personapack constructs the new PackEntry with it.
+
+    Ladder (best→worst): tested-with-receipt > proven-in-forge > seed.
+    A bump moves ONE rung toward tested-with-receipt.
+    """
+    if current_grade not in PACK_GRADES:
+        raise ValueError(f"grade {current_grade!r} not in {PACK_GRADES}")
+    i = PACK_GRADES.index(current_grade)
+    return PACK_GRADES[max(0, i - 1)]
+
+
+# ── honest stubs: real cross-package integration we cannot test here ─────────
+def adopt_rule(request: dict, *, by: str, **_) -> dict:
+    """STUB. A real rule-adopt would call rulecatcher's adopt path:
+
+        rulecatcher.engine.adopt_rules(connection, rule_ids, actor=by,
+                                       source="goldenreq", reason=<verdict reason>)
+
+    (see packages/rulecatcher/src/rulecatcher/engine.py, `adopt_rules`).
+    That needs a live rulecatcher sqlite `Connection` and real candidate rule ids
+    threaded through the request — wiring goldenreq cannot construct or exercise
+    in isolation. Not faked.
+    """
+    raise NotImplementedError(
+        "rule-adopt: wire request.candidate_id (rule ids) + a rulecatcher "
+        "Connection to rulecatcher.engine.adopt_rules(actor=by, source='goldenreq'). "
+        "Deliberately unimplemented — no fake integration.")
+
+
+def promote_template(request: dict, *, by: str, **_) -> dict:
+    """STUB. A real template-promote would move a forged language/template from
+    candidate into the canonical set (the chainaios `construct_language` /
+    template store). That store's promotion API is not defined yet, so there is
+    nothing honest to call. Not faked.
+    """
+    raise NotImplementedError(
+        "template-promote: no canonical-template promotion API exists to call "
+        "yet; when one does, dispatch request.candidate_id to it here. "
+        "Deliberately unimplemented — no fake integration.")

goldenreq/queue.py

@@ -0,0 +1,132 @@
+"""queue.py — the goldenization request queue (append-only JSONL).
+
+Same append-only ledger idiom as the KB reward record and base/acceptance's
+verdict corpus (a `write` is one JSON line; nothing is ever mutated in place).
+
+A REQUEST is a *gauge-passed, handler-pending* event: a gauge — the bandit's
+2×🏆 on a constructed chain, a rulecatcher candidate rule, a forged
+language/template, a personapack `activation_grade` claim — asks for a
+promotion it may NOT grant itself. The request carries its RECEIPTS (evidence)
+and sits pending until a handler rules on it (see ``verdict.py``). This is
+JobWorld's ``supposedly_done`` made explicit, and base/acceptance's
+``handler.verdict == "escalate"`` (gauge-passed, handler-pending) as a queue.
+
+THE LAW: the gauge never certifies itself. Filing a request is the ONLY thing a
+gauge may do toward promotion; the promotion effect fires only on an accepted
+verdict.
+"""
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+# the four things that can be promoted (each has a real gauge upstream)
+KINDS: tuple[str, ...] = (
+    "chain-golden",      # a constructed bandit chain earned 🏆 twice (chainaios)
+    "rule-adopt",        # a rulecatcher candidate rule wants adoption
+    "template-promote",  # a forged language / template wants to become canon
+    "pack-grade-bump",   # a personapack PackEntry wants a higher activation_grade
+)
+
+QUEUE_ENV = "GOLDENREQ_QUEUE_PATH"
+VERDICTS_ENV = "GOLDENREQ_VERDICTS_PATH"
+DEFAULT_QUEUE = "goldenreq_queue.jsonl"
+DEFAULT_VERDICTS = "verdicts.jsonl"
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def resolve_queue_path(path: str | os.PathLike | None = None) -> Path:
+    return Path(path or os.environ.get(QUEUE_ENV) or DEFAULT_QUEUE)
+
+
+def resolve_verdicts_path(queue_path: str | os.PathLike | None = None) -> Path:
+    """The verdicts corpus sits beside the queue (or at $GOLDENREQ_VERDICTS_PATH).
+    Mirrors base/acceptance's `resolve_corpus_path` — env override, else default."""
+    env = os.environ.get(VERDICTS_ENV)
+    if env:
+        return Path(env)
+    return resolve_queue_path(queue_path).parent / DEFAULT_VERDICTS
+
+
+def _append(path: Path, record: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(json.dumps(record, sort_keys=True) + "\n")
+
+
+def _read_all(path: Path) -> list[dict]:
+    out: list[dict] = []
+    if not Path(path).exists():
+        return out
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except Exception:
+                continue
+    return out
+
+
+def new_request_id() -> str:
+    return "gr-" + uuid.uuid4().hex[:24]
+
+
+def file_request(kind: str, candidate_id: str, evidence: list[str],
+                 requested_promotion: str, requester: str,
+                 queue_path: str | os.PathLike | None = None) -> str:
+    """Append one goldenization request to the queue. Returns its request_id.
+
+    `evidence` = the receipts (graded KB note paths, cert ids, forge reports).
+    A request with no evidence is still filed (honest — an unevidenced ask is a
+    weak ask a handler will likely reject), but evidence is what an acceptance
+    model later learns from, so gauges SHOULD attach it.
+    """
+    if kind not in KINDS:
+        raise ValueError(f"kind {kind!r} not in {KINDS}")
+    rid = new_request_id()
+    rec = {
+        "request_id": rid,
+        "ts": now_iso(),
+        "kind": kind,
+        "candidate_id": candidate_id,
+        "evidence": list(evidence or []),
+        "requested_promotion": requested_promotion,
+        "requester": requester,
+        "status": "pending",
+    }
+    _append(resolve_queue_path(queue_path), rec)
+    return rid
+
+
+def get_request(request_id: str, queue_path: str | os.PathLike | None = None) -> dict | None:
+    for rec in _read_all(resolve_queue_path(queue_path)):
+        if rec.get("request_id") == request_id:
+            return rec
+    return None
+
+
+def ruled_request_ids(queue_path: str | os.PathLike | None = None) -> set[str]:
+    """request_ids that already carry a handler verdict (accept OR reject)."""
+    vpath = resolve_verdicts_path(queue_path)
+    return {v.get("context_ref") for v in _read_all(vpath) if v.get("context_ref")}
+
+
+def list_pending(queue_path: str | os.PathLike | None = None) -> list[dict]:
+    """Requests with no handler verdict yet — the handler's inbox.
+
+    A request is pending ⇔ no verdict record points at it (verdict.context_ref
+    == request_id). That is base/acceptance's `escalate` state: gauge-passed,
+    handler-pending.
+    """
+    ruled = ruled_request_ids(queue_path)
+    return [r for r in _read_all(resolve_queue_path(queue_path))
+            if r.get("request_id") not in ruled]

goldenreq/verdict.py

@@ -0,0 +1,133 @@
+"""verdict.py — the HANDLER ruling on a goldenization request.
+
+`accept` / `reject` are the ONLY authority in this package. Nothing self-promotes:
+a promotion effect (effects.py) fires only when a handler `accept`s. A `reject`
+carries a reason — those reasons are the HARD NEGATIVES for the learned
+acceptance model that later staffs this gate.
+
+Verdict record shape — MIRRORS base/acceptance's `acceptance.schema.Verdict`
+(read via `git show acceptance-handler:base/acceptance/acceptance/schema.py`).
+We do NOT import across branches; we reproduce the shape as a plain dict so the
+verdicts corpus is drop-in compatible with that reader. Field mapping:
+
+    base/acceptance Verdict field   ← goldenreq source
+    ------------------------------    ----------------------------------------
+    id                              ← a fresh verdict id ("vd-…")
+    ts                              ← ruling timestamp (ISO-8601)
+    domain                          ← "goldenize"  (base lists this exact domain)
+    artifact_ref                    ← request.candidate_id (what was judged)
+    context_ref                     ← request.request_id   (the request it belongs to)
+    gauge.source                    ← request.requester    (the self-claiming gauge)
+    gauge.score                     ← request.requested_promotion (the gauge's claim)
+    gauge.reasons                   ← request.evidence     (the receipts it filed)
+    handler.verdict                 ← "accept" | "reject"  (base also has "escalate"
+                                       = still-pending; a pending request is exactly
+                                       that state, so it has NO verdict record yet)
+    handler.actor                   ← `by`, coerced to "human:<who>" / "model:<id>"
+    handler.reasons                 ← [reason]  (rejections MUST carry one)
+    handler.edits_made              ← None (goldenreq handlers rule, they don't edit)
+    outcome                         ← the promotion effect's result on accept, else None
+"""
+from __future__ import annotations
+
+import os
+import re
+import uuid
+
+from . import effects
+from .queue import (
+    get_request, now_iso, resolve_queue_path, resolve_verdicts_path,
+    ruled_request_ids, _append, _read_all,
+)
+
+ACTOR_PATTERN = re.compile(r"^(human|model):.+$")  # base/acceptance schema.ACTOR_PATTERN
+
+
+def new_verdict_id() -> str:
+    return "vd-" + uuid.uuid4().hex[:24]
+
+
+def _actor(by: str) -> str:
+    """Coerce `by` to the base schema's `^(human|model):.+$` actor form.
+    A bare name is assumed human (the default handler is a person doing QA)."""
+    by = (by or "").strip()
+    if not by:
+        raise ValueError("a verdict requires `by` (the ruling actor)")
+    return by if ACTOR_PATTERN.match(by) else f"human:{by}"
+
+
+def _build_verdict(request: dict, decision: str, by: str,
+                   reasons: list[str], outcome: dict | None) -> dict:
+    """One acceptance event, in base/acceptance Verdict shape (see module docstring)."""
+    return {
+        "id": new_verdict_id(),
+        "ts": now_iso(),
+        "domain": "goldenize",
+        "artifact_ref": request["candidate_id"],
+        "context_ref": request["request_id"],
+        "gauge": {
+            "source": request.get("requester", ""),
+            "score": request.get("requested_promotion"),
+            "reasons": list(request.get("evidence", [])),
+        },
+        "handler": {
+            "verdict": decision,
+            "actor": _actor(by),
+            "reasons": list(reasons),
+            "edits_made": None,
+        },
+        "outcome": outcome,
+    }
+
+
+def _guard(request_id: str, queue_path) -> dict:
+    request = get_request(request_id, queue_path=queue_path)
+    if request is None:
+        raise ValueError(f"no such request: {request_id}")
+    if request_id in ruled_request_ids(queue_path):
+        raise ValueError(f"request {request_id} already has a verdict (no double-ruling)")
+    return request
+
+
+def accept(request_id: str, by: str, reason: str = "", *,
+           queue_path: str | os.PathLike | None = None,
+           verdicts_path: str | os.PathLike | None = None,
+           effect_kwargs: dict | None = None) -> dict:
+    """ACCEPT a request → fire its promotion effect, then record the verdict.
+
+    The effect runs BEFORE the record is written so its result is captured in
+    `outcome` (the audit trail). If the effect raises, nothing is recorded and
+    the request stays pending — no half-promotion. Returns the verdict record.
+    """
+    from pathlib import Path
+    request = _guard(request_id, queue_path)
+    outcome = effects.dispatch(request, by=_actor(by), **(effect_kwargs or {}))
+    verdict = _build_verdict(request, "accept", by, [reason] if reason else [], outcome)
+    vpath = Path(verdicts_path) if verdicts_path is not None else resolve_verdicts_path(queue_path)
+    _append(vpath, verdict)
+    return verdict
+
+
+def reject(request_id: str, by: str, reason: str, *,
+           queue_path: str | os.PathLike | None = None,
+           verdicts_path: str | os.PathLike | None = None) -> dict:
+    """REJECT a request → NO effect, record the verdict with its reason.
+
+    The reason is mandatory: rejections are the hard negatives the learned
+    acceptance model trains on. Nothing is promoted.
+    """
+    if not (reason or "").strip():
+        raise ValueError("reject requires a reason (it is the hard negative)")
+    request = _guard(request_id, queue_path)
+    verdict = _build_verdict(request, "reject", by, [reason], None)
+    from pathlib import Path
+    vpath = Path(verdicts_path) if verdicts_path is not None else resolve_verdicts_path(queue_path)
+    _append(vpath, verdict)
+    return verdict
+
+
+def list_verdicts(queue_path: str | os.PathLike | None = None,
+                  verdicts_path: str | os.PathLike | None = None) -> list[dict]:
+    from pathlib import Path
+    vpath = Path(verdicts_path) if verdicts_path is not None else resolve_verdicts_path(queue_path)
+    return _read_all(vpath)

goldenreq-0.3.0.dist-info/METADATA

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: goldenreq
+Version: 0.3.0
+Summary: The acceptance gate for goldenization: gauges FILE requests carrying receipts; a handler ACCEPTS/REJECTS; only an accept fires the promotion effect. Nothing self-promotes.
+Requires-Python: >=3.11

goldenreq-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+goldenreq/__init__.py,sha256=Y95IRc1wCYU-X3rVkF4hcPVOtVDmbu9nSDXXdXRAG0Q,1391
+goldenreq/cli.py,sha256=so4bcVTInq5oRsXf7hdTORBXe2VtNUZHQ29ELenDPdk,2306
+goldenreq/effects.py,sha256=6O5twoewSxkHVU4RxLfBTxKP2QaHJz6hZqkOqbR8o0o,5208
+goldenreq/queue.py,sha256=Qus0wAGuF_YdKK6HkXpzshg9KwXJob13TIl_QU1DxGQ,4991
+goldenreq/verdict.py,sha256=SMqN2cxMkcXvvabjsqBw98H_TqSCMg-HGeI83Z2BIXg,6010
+goldenreq-0.3.0.dist-info/METADATA,sha256=UOF9FDyZmLAG_7O7TiwX1N1GMGiVtB_8_ASd4cAQZJk,258
+goldenreq-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+goldenreq-0.3.0.dist-info/entry_points.txt,sha256=fWR8LNGor1SxWas2Fj6AmVOxeDGvvjVYmkCboe5dlLc,49
+goldenreq-0.3.0.dist-info/top_level.txt,sha256=zddDlHNcMlMYu0sgmXNVNleddIlCAeg2Oauf5c0KyAQ,10
+goldenreq-0.3.0.dist-info/RECORD,,

goldenreq-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

goldenreq-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+goldenreq = goldenreq.cli:main

goldenreq-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+goldenreq