@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/extensions/vendor/openviking-pi/patches/0010-typed-lessons.patch

@@ -0,0 +1,448 @@
+diff --git a/extensions/vendor/openviking-pi/NOTICE b/extensions/vendor/openviking-pi/NOTICE
+--- a/extensions/vendor/openviking-pi/NOTICE
++++ b/extensions/vendor/openviking-pi/NOTICE
+@@ -51,6 +51,8 @@ Changed by the quickreviewd maintainers, 2026-08-20:
+      prompt across every scope (2026-10-07).
+   9. A review session's memory search, read and browse tools stay inside the
+      same memory areas (2026-10-07).
++ 10. `viking_write` takes a structured `lesson` and writes the lesson's
++     header line from it, refusing unknown lens ids (2026-10-07).
+ 
+ Plus vendoring scaffolding: build-conformance fixes for this repo's stricter
+ tsconfig, ambient type declarations for uninstalled packages, three unused
+diff --git a/extensions/vendor/openviking-pi/README.md b/extensions/vendor/openviking-pi/README.md
+--- a/extensions/vendor/openviking-pi/README.md
++++ b/extensions/vendor/openviking-pi/README.md
+@@ -1,7 +1,7 @@
+ # openviking-pi — vendored, patched fork
+ 
+ The OpenViking pi extension our sessions load. Vendored, not depended on:
+-upstream ships it as an `examples/` directory, not a package, and we need nine
++upstream ships it as an `examples/` directory, not a package, and we need ten
+ behaviour changes that upstream has no reason to make.
+ 
+ | | |
+@@ -20,7 +20,7 @@ fails on drift between the two.
+ 
+ ## Why a fork rather than configuration
+ 
+-Every one of the nine patches was tried as configuration first and does not
++Every one of the ten patches was tried as configuration first and does not
+ exist there. The evidence is a spike against a **running v0.4.15 server plus
+ the pinned pi 0.84.1** — `assets/findings.md` in the issue tracker,
+ with transcripts. Read it before changing anything here; several of its
+@@ -28,9 +28,9 @@ findings contradict the OpenViking docs, which lead the tag.
+ 
+ ## The patch series
+ 
+-Nine numbered behaviour patches, applied in order over the vendored upstream
++Ten numbered behaviour patches, applied in order over the vendored upstream
+ files, plus one unnumbered scaffolding patch. They live in `patches/` as
+-`git apply`-able diffs — verified by applying all ten, in order, to a
++`git apply`-able diffs — verified by applying all eleven, in order, to a
+ pristine `v0.4.15` extraction and diffing the result against this directory:
+ byte-identical. (`patches/` and `upstream.json` are meta and are not themselves
+ part of the reproduced tree.) Every hunk they add carries a greppable marker:
+@@ -378,6 +378,31 @@ of a round until S9 decides how they are delivered.
+ Touches: `qcr-hint.ts` (the scope rules), `tools.ts` (the three read tools),
+ `index.ts` (the provider, the prompt line, the banner).
+ 
++### 0010 — typed lessons: `viking_write` writes the header (S8)
++
++The EOD curator wrote its lessons as prose — 10 of 17 with no machine header,
++the rest spelling type, lens and evidence three ways in the body — so nothing
++could tell which lens a lesson was for, whether it said "look for X" or "do not
++raise X", or which candidate it adopted.
++
++* **A structured `lesson` parameter** (top level for one entry, and per entry
++  of `entries`): `{kind, lens, class, paths, evidence}`. The tool renders
++  `#lesson kind=… lens=… class=… paths=… evidence=…` as the entry's FIRST line
++  (`qcr-lesson.ts`), tags the entry `lesson`, and writes the author's prose
++  after it. The daemon's reader is `src/memory/lessons.ts` `parseLesson`; the
++  fork test pins the two against each other.
++* **Refusals, before anything is sent:** an unknown lens id (the list is
++  `LESSON_LENS_IDS`, pinned equal to the daemon's `ALL_PASSES`; a short
++  `baseline` reads as `pass-baseline`), a kind outside the four, a class that
++  is not a slug, a glob or ref with whitespace or a comma, no evidence, a
++  target outside `memories/experiences/`, and `content` that opens with a
++  header of its own.
++* **Nothing else changes.** An entry without `lesson` is written exactly as
++  before; a batch may mix the two.
++
++Touches: `qcr-lesson.ts` (new), `qcr-write.ts` (the builder), `tools.ts` (the
++schema and one guideline).
++
+ ## Rebasing onto a newer upstream
+ 
+ ```sh
+@@ -390,16 +415,16 @@ git -C /tmp/ov checkout <new-tag>
+ for p in extensions/vendor/openviking-pi/patches/0*.patch; do
+   git apply --3way "$p" || echo "RESOLVE: $p"
+ done
+-# 3. Re-verify all nine patches, then:
++# 3. Re-verify all ten patches, then:
+ timeout 900 npm test && npm run build
+ ```
+ 
+ Then update `extension_commit` and `version` in `config.toml [openviking]`,
+ the base commit in `NOTICE` and in the table above, and re-run the live
+-verification below. A bump re-verifies **all nine** patches — a patch that no
++verification below. A bump re-verifies **all ten** patches — a patch that no
+ longer applies is a patch whose reason may have changed, not a patch to drop.
+ 
+-`tests/openviking-fork.test.ts` is the guard rail: it asserts the nine patches
++`tests/openviking-fork.test.ts` is the guard rail: it asserts the ten patches
+ are still present (markers, and the *absence* of what each one removed) and
+ that the pinned commit here matches `config.toml`. It cannot tell you whether
+ upstream grew a *new* compaction handler or a *new* write tool — read the
+diff --git a/extensions/vendor/openviking-pi/qcr-write.ts b/extensions/vendor/openviking-pi/qcr-write.ts
+--- a/extensions/vendor/openviking-pi/qcr-write.ts
++++ b/extensions/vendor/openviking-pi/qcr-write.ts
+@@ -24,6 +24,8 @@
+ import { createHash } from "node:crypto";
+ // [QCR PATCH 6] a batch is routed by its entries (`routeWrite`)
+ import { routeNamespace, type NamespaceRoute } from "./qcr-namespaces.js";
++// [QCR PATCH 10] a typed lesson's header is rendered from `lesson`
++import { withLessonHeader } from "./qcr-lesson.js";
+ 
+ /** Memory targets keep a text-extension allowlist server-side; these are the
+  * two we ever author. */
+@@ -75,6 +77,9 @@ export interface WriteRequestInput {
+   mode?: unknown;
+   expect_hash?: unknown;
+   wait?: unknown;
++  /** [QCR PATCH 10] A structured lesson ({kind, lens, class, paths,
++   * evidence}): the entry's header is rendered from it (qcr-lesson.ts). */
++  lesson?: unknown;
+ }
+ 
+ /** `sha256:<lowercase-hex>` — the shape batch-write's `base_hash` wants. */
+@@ -185,7 +190,18 @@ export function buildWriteRequest(input: WriteRequestInput): WriteRequestResult
+   const tags = normalizeTags(input.tags);
+   if (!tags.ok) return { ok: false, error: tags.error ?? "Invalid tags." };
+ 
+-  const body = renderMemoryBody(input.content, tags.tags);
++  // [QCR PATCH 10] A typed lesson: the header is the tool's to write, from
++  // the structured parameter, on the entry's first line — and the entry is
++  // tagged `lesson` for retrieval too.
++  let content = input.content;
++  if (input.lesson !== undefined && input.lesson !== null) {
++    const lesson = withLessonHeader(uri, input.content, input.lesson);
++    if (!lesson.ok) return { ok: false, error: lesson.error };
++    content = lesson.content;
++    if (!tags.tags.includes("lesson") && tags.tags.length < MAX_TAGS) tags.tags.push("lesson");
++  }
++
++  const body = renderMemoryBody(content, tags.tags);
+   if (!body.trim()) return { ok: false, error: "viking_write needs non-empty `content`." };
+ 
+   let precondition: BatchWriteOperation["precondition"];
+@@ -242,6 +258,8 @@ export interface BatchEntryInput {
+   tags?: unknown;
+   mode?: unknown;
+   expect_hash?: unknown;
++  /** [QCR PATCH 10] */
++  lesson?: unknown;
+ }
+ 
+ /** One entry (`uri` + `content`, as `WriteRequestInput`) or several
+@@ -255,6 +273,8 @@ export interface BatchWriteInput {
+   expect_hash?: unknown;
+   wait?: unknown;
+   entries?: unknown;
++  /** [QCR PATCH 10] the one entry's lesson (with `uri` + `content`). */
++  lesson?: unknown;
+ }
+ 
+ export interface BatchEntryBuilt {
+@@ -330,7 +350,8 @@ export function routeWrite(
+  * the deepest directory they all sit under.
+  */
+ export function buildBatchWriteRequest(input: BatchWriteInput): BatchRequestResult {
+-  const hasSingle = input.uri !== undefined || input.content !== undefined;
++  const hasSingle =
++    input.uri !== undefined || input.content !== undefined || input.lesson !== undefined;
+   if (input.entries === undefined) {
+     const one = buildWriteRequest({
+       uri: input.uri,
+@@ -339,6 +360,7 @@ export function buildBatchWriteRequest(input: BatchWriteInput): BatchRequestResu
+       mode: input.mode,
+       expect_hash: input.expect_hash,
+       wait: input.wait,
++      lesson: input.lesson,
+     });
+     if (!one.ok) return one;
+     return {
+@@ -374,6 +396,7 @@ export function buildBatchWriteRequest(input: BatchWriteInput): BatchRequestResu
+       tags: entry.tags,
+       mode: entry.mode,
+       expect_hash: entry.expect_hash,
++      lesson: entry.lesson,
+     });
+     if (!one.ok) return { ok: false, error: `Entry ${i + 1}: ${one.error} Nothing was written.` };
+     const op = one.request.operations[0]!;
+diff --git a/extensions/vendor/openviking-pi/tools.ts b/extensions/vendor/openviking-pi/tools.ts
+--- a/extensions/vendor/openviking-pi/tools.ts
++++ b/extensions/vendor/openviking-pi/tools.ts
+@@ -8,6 +8,8 @@ import { buildBatchWriteRequest, routeWrite } from "./qcr-write.js";
+ import { failureText, isNotFound, isPreconditionConflict } from "./qcr-honest.js";
+ // [QCR PATCH 5]
+ import { namespaceNote, ownNamespaceName, routeNamespace } from "./qcr-namespaces.js";
++// [QCR PATCH 10]
++import { LESSON_KINDS } from "./qcr-lesson.js";
+ // [QCR PATCH 9]
+ import {
+   browsableInScope,
+@@ -288,6 +290,16 @@ export function registerTools(
+   //
+   // `viking_write` is therefore the ONLY write tool a session can reach.
+   if (!leaf) {
++    // [QCR PATCH 10] A curated lesson's header, as structured fields: the
++    // tool renders `#lesson kind=… lens=… class=… paths=… evidence=…` from
++    // them (qcr-lesson.ts) and refuses an unknown lens id.
++    const lessonParam = Type.Object({
++      kind: StringEnum(LESSON_KINDS),
++      lens: Type.Array(Type.String(), { description: "Built lens ids the lesson is for, e.g. ['pass-baseline','pass-validate']" }),
++      class: Type.String({ description: "Class slug the lesson covers, e.g. 'baseline.pre-existing-scope' — reuse a candidate's class" }),
++      paths: Type.Array(Type.String(), { description: "Path globs it applies to; ['**'] for the whole repo" }),
++      evidence: Type.Array(Type.String(), { description: "Refs: pr:<n>, comment:<id>, case:<name>, commit:<sha>, cand:c<id>" }),
++    }, { description: "A typed lesson (experiences/ only): the tool writes the header line from these fields" });
+     pi.registerTool({
+       name: "viking_write",
+       label: "Viking Write",
+@@ -299,6 +311,8 @@ export function registerTools(
+         "Several entries at once go in ONE call as `entries` — never as parallel calls into the same directory.",
+         "Prefer mode 'create' with a fresh filename. Only 'replace' an entry you just read, passing its hash as expect_hash.",
+         "A 409 REFUSED means the file changed (or already exists) — re-read it and decide, never retry blindly. A busy directory is retried for you; if it stays busy, try again in a minute.",
++        // [QCR PATCH 10]
++        "A curated lesson (experiences/) goes with `lesson: {kind, lens, class, paths, evidence}` — the tool writes its header line; `content` is the lesson's prose only. Cite the learner candidate a lesson adopts as `cand:c<id>` in evidence.",
+         ...nsGuidelines,
+       ],
+       parameters: Type.Object({
+@@ -307,6 +321,8 @@ export function registerTools(
+         tags: Type.Optional(Type.Array(Type.String(), { description: "Convention tags without '#', e.g. ['pinned','review-ops']" })),
+         mode: Type.Optional(StringEnum(["create", "replace"] as const)),
+         expect_hash: Type.Optional(Type.String({ description: "Required for mode 'replace': sha256 of the CURRENT stored bytes" })),
++        // [QCR PATCH 10] a typed lesson — the header is rendered from this.
++        lesson: Type.Optional(lessonParam),
+         // [QCR PATCH 6] several entries, one batch-write under one root.
+         entries: Type.Optional(Type.Array(
+           Type.Object({
+@@ -315,6 +331,8 @@ export function registerTools(
+             tags: Type.Optional(Type.Array(Type.String())),
+             mode: Type.Optional(StringEnum(["create", "replace"] as const)),
+             expect_hash: Type.Optional(Type.String()),
++            // [QCR PATCH 10]
++            lesson: Type.Optional(lessonParam),
+           }),
+           { description: "Several entries written as ONE batch (instead of uri + content). They must share a directory; the batch lands whole or not at all." },
+         )),
+diff --git a/extensions/vendor/openviking-pi/qcr-lesson.ts b/extensions/vendor/openviking-pi/qcr-lesson.ts
+new file mode 100644
+--- /dev/null
++++ b/extensions/vendor/openviking-pi/qcr-lesson.ts
+@@ -0,0 +1,204 @@
++// QCR FORK — file added by PATCH 10 (typed lessons). Not upstream.
++// a curated lesson carries a machine header, written by the tool.
++//
++// The pure half, kept free of pi and of the OV client so
++// `tests/openviking-fork.test.ts` can exercise it (`tools.ts` cannot be
++// imported from a test).
++//
++// The EOD curator wrote its lessons as prose: 10 of 17 carried no machine
++// header, the rest spelled type, lens and evidence three ways in the body, and
++// nothing could tell which lens a lesson was for or which human evidence it
++// rested on. `viking_write` now takes a structured `lesson` parameter and
++// RENDERS the header itself, on the entry's first line:
++//
++//   #lesson kind=<repo-fact|look-for|dont-raise|convention> lens=<ids>
++//           class=<slug> paths=<globs> evidence=<refs>
++//
++// (one line; lists comma-separated; no whitespace in a value). The daemon's
++// reader is `src/memory/lessons.ts` (`parseLesson`); the test suite pins this
++// renderer against it, and `LESSON_LENS_IDS` here equal to the daemon's built
++// passes (`ALL_PASSES`) — one list, two readers, like PATCH 9's areas. An
++// unknown lens id is REFUSED: a lesson for a lens nobody runs would be
++// delivered to nobody. A lesson is written into `experiences/` and nowhere
++// else, and its content may not carry a header of its own.
++
++/** The lesson kinds — the daemon's `LESSON_KINDS`. */
++export const LESSON_KINDS: readonly string[] = ["repo-fact", "look-for", "dont-raise", "convention"];
++
++/** The lens ids a lesson may name: every pass the daemon builds, the
++ * validator included. Pinned equal to `src/passes.ts` `ALL_PASSES`. */
++export const LESSON_LENS_IDS: readonly string[] = [
++  "pass-baseline",
++  "pass-ui",
++  "pass-contracts",
++  "pass-data-safety",
++  "pass-security",
++  "pass-statelessness",
++  "pass-prod-risk",
++  "pass-delivery",
++  "pass-intent",
++  "pass-placement",
++  "pass-simplicity",
++  "pass-backcompat",
++  "pass-concurrency",
++  "pass-ask-human",
++  "pass-widened",
++  "pass-roundtrip",
++  "pass-deferred",
++  "pass-bounds",
++  "pass-claims",
++  "pass-rollout",
++  "pass-behaviour-delta",
++  "pass-sweep",
++  "pass-tests",
++  "pass-maintainability",
++  "pass-duplication",
++  "pass-abstraction",
++  "pass-consistency",
++  "pass-style",
++  "pass-lint-conformance",
++  "pass-validate",
++];
++
++const CLASS_RE = /^[a-z0-9][a-z0-9._-]{0,79}$/;
++const GLOB_RE = /^[^\s,]{1,200}$/;
++const REF_RE = /^[a-z][a-z0-9-]{0,19}:[^\s,]{1,200}$/;
++const LIMITS = { lenses: 8, paths: 12, evidence: 16 };
++
++/** Where a lesson may be written: a file directly in a user's
++ * `memories/experiences/`. */
++const LESSON_URI_RE = /^viking:\/\/user\/[^/\s]+\/memories\/experiences\/[^/\s]+$/;
++
++export interface LessonHeaderOk {
++  ok: true;
++  header: string;
++}
++
++export interface LessonHeaderError {
++  ok: false;
++  error: string;
++}
++
++function list(raw: unknown): string[] | null {
++  if (raw === undefined || raw === null) return [];
++  const items = Array.isArray(raw) ? raw : typeof raw === "string" ? raw.split(",") : null;
++  if (!items) return null;
++  const out: string[] = [];
++  for (const v of items) {
++    if (typeof v !== "string") return null;
++    const t = v.trim();
++    if (t !== "" && !out.includes(t)) out.push(t);
++  }
++  return out;
++}
++
++/**
++ * The header line for a structured `lesson`, or the sentence saying what is
++ * wrong with it. Every field is required; `baseline` is read as
++ * `pass-baseline`; nothing unknown is accepted.
++ */
++export function buildLessonHeader(
++  raw: unknown,
++  known: readonly string[] = LESSON_LENS_IDS,
++): LessonHeaderOk | LessonHeaderError {
++  if (!raw || typeof raw !== "object" || Array.isArray(raw))
++    return { ok: false, error: "`lesson` must be an object {kind, lens, class, paths, evidence}." };
++  const o = raw as Record<string, unknown>;
++  const unknown = Object.keys(o).filter(
++    (k) => !["kind", "lens", "class", "paths", "evidence"].includes(k),
++  );
++  if (unknown.length > 0) return { ok: false, error: `Unknown lesson field(s): ${unknown.join(", ")}.` };
++  const kind = typeof o["kind"] === "string" ? o["kind"].trim().toLowerCase() : "";
++  if (!LESSON_KINDS.includes(kind))
++    return { ok: false, error: `lesson.kind must be one of ${LESSON_KINDS.join(", ")}.` };
++  const lensRaw = list(o["lens"]);
++  if (!lensRaw || lensRaw.length === 0)
++    return { ok: false, error: "lesson.lens must name at least one lens id (e.g. pass-baseline)." };
++  if (lensRaw.length > LIMITS.lenses)
++    return { ok: false, error: `lesson.lens names ${lensRaw.length} lenses; at most ${LIMITS.lenses}.` };
++  const lens: string[] = [];
++  const bad: string[] = [];
++  for (const id of lensRaw) {
++    const t = id.toLowerCase();
++    const k = known.includes(t) ? t : known.includes(`pass-${t}`) ? `pass-${t}` : null;
++    if (k === null) bad.push(id);
++    else if (!lens.includes(k)) lens.push(k);
++  }
++  if (bad.length > 0)
++    return {
++      ok: false,
++      error: `Unknown lens id(s): ${bad.join(", ")}. A lesson names built passes only (${known.join(", ")}).`,
++    };
++  const cls = typeof o["class"] === "string" ? o["class"].trim().toLowerCase() : "";
++  if (!CLASS_RE.test(cls))
++    return {
++      ok: false,
++      error: "lesson.class must be a slug: lowercase letters, digits, '.', '_' or '-' (e.g. baseline.pre-existing-scope).",
++    };
++  const paths = list(o["paths"]);
++  if (!paths || paths.length === 0)
++    return { ok: false, error: "lesson.paths must name at least one path glob (`**` for the whole repo)." };
++  if (paths.length > LIMITS.paths)
++    return { ok: false, error: `lesson.paths names ${paths.length} globs; at most ${LIMITS.paths}.` };
++  const badGlob = paths.find((p) => !GLOB_RE.test(p));
++  if (badGlob !== undefined)
++    return {
++      ok: false,
++      error: `Path glob "${badGlob}" may not contain whitespace or a comma (write a brace expansion as separate globs).`,
++    };
++  const evidence = list(o["evidence"]);
++  if (!evidence || evidence.length === 0)
++    return {
++      ok: false,
++      error: "lesson.evidence must cite at least one ref (pr:<n>, comment:<id>, case:<name>, commit:<sha>, cand:<id>) — no lesson without evidence.",
++    };
++  if (evidence.length > LIMITS.evidence)
++    return { ok: false, error: `lesson.evidence cites ${evidence.length} refs; at most ${LIMITS.evidence}.` };
++  const badRef = evidence.find((r) => !REF_RE.test(r));
++  if (badRef !== undefined)
++    return {
++      ok: false,
++      error: `Evidence ref "${badRef}" must be <kind>:<id> with no whitespace or comma (e.g. pr:5312, cand:c42).`,
++    };
++  return {
++    ok: true,
++    header: [
++      "#lesson",
++      `kind=${kind}`,
++      `lens=${lens.join(",")}`,
++      `class=${cls}`,
++      `paths=${paths.join(",")}`,
++      `evidence=${evidence.join(",")}`,
++    ].join(" "),
++  };
++}
++
++/**
++ * The content of a lesson entry: the rendered header on the first line, the
++ * author's prose after it. Refused when the target is not in `experiences/`
++ * or the prose already opens with a header of its own — the header is the
++ * tool's to write, so a hand-typed one can neither duplicate nor contradict
++ * it.
++ */
++export function withLessonHeader(
++  uri: string,
++  content: unknown,
++  lesson: unknown,
++  known: readonly string[] = LESSON_LENS_IDS,
++): { ok: true; content: string } | LessonHeaderError {
++  if (!LESSON_URI_RE.test(uri))
++    return {
++      ok: false,
++      error: `A lesson is written into experiences/ (viking://user/<user>/memories/experiences/<name>.md); got "${uri}".`,
++    };
++  const built = buildLessonHeader(lesson, known);
++  if (!built.ok) return built;
++  const prose = String(content ?? "").trim();
++  if (prose === "") return { ok: false, error: "A lesson needs its one-sentence rule in `content`." };
++  if (/^#lesson\b/i.test(prose) || /^#[a-z0-9-]+\s+kind=/i.test(prose))
++    return {
++      ok: false,
++      error: "Leave the header out of `content` — the tool writes it from `lesson`. Start `content` with the lesson's prose.",
++    };
++  return { ok: true, content: `${built.header}\n\n${prose}` };
++}