@isparling/engram-cli 0.1.0 → 0.2.0

package/README.md

@@ -19,12 +19,17 @@ engram rollup approve --bullets <path> --expect <rollup-hash>
 engram space register --binding <path>
 engram space select <space-id>
 engram space status
+engram space refresh
 engram recall --query <text> --audience <id> [--source-class <class>]
 engram render --view <id> --audience <id> --delivery <id> --model <provider/model>
 ```
 
 Run `engram --help` for current command usage.
 
+`space refresh` runs the active space's qmd update through Engram's guarded
+boundary: scoped config/cache variables, normalized `PWD`, config validation,
+symlink checks, and registry freshness recording.
+
 ## Requirements
 
 Requires [Bun](https://bun.sh) to run. Install:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isparling/engram-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "The CLI binary backing the @isparling/engram-harness extension's knowledge submission, reconciliation, recall, and rendering pipeline.",

package/src/artifactReplacement.ts

@@ -0,0 +1,208 @@
+// Artifact-root-confined atomic replacement: the write mechanic pack
+// materializers use to regenerate compatibility views (prescription YAML,
+// consultation logs, ...) from committed records.
+//
+// Authorization layering, in order:
+//
+// 1. The requested root is pack-selected configuration — it may name any
+//    directory — but it is only ever a candidate. The binding remains the
+//    final authorization boundary: the canonicalized root must sit inside an
+//    active `writeRoot` AND inside the space root, or the request is refused.
+// 2. Every existing parent of the target is resolved with realpath and must
+//    stay inside the canonicalized root, so a symlinked directory cannot move
+//    the write outside even when its destination is itself inside the binding.
+// 3. A symlinked target is refused outright rather than written through.
+// 4. Current bytes are compared first; atomicWriteFile runs only on a real
+//    change, so repeated materialization is a byte-identical no-op.
+
+import { lstat, mkdir, readFile, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { atomicWriteFile } from "./atomicWrite.ts";
+import type { ActiveSpace } from "./spaceRegistry.ts";
+import type { ArtifactReplacementResult } from "./captureTypes.ts";
+import type { KnowledgeError, KnowledgeResult } from "./knowledgeTypes.ts";
+
+export type ArtifactReplacementRequest = {
+  root: string;
+  relativePath: string;
+  content: string;
+};
+
+function artifactError(code: string, message: string, field?: string): KnowledgeError {
+  return field === undefined
+    ? { kind: "artifact", code, message }
+    : { kind: "artifact", code, field, message };
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+// Same containment test spaceRegistry uses for binding validation: relative()
+// based, so a candidate equals-or-under check cannot be fooled by ".." or
+// absolute spellings.
+function containsPath(root: string, candidate: string): boolean {
+  const pathFromRoot = relative(root, candidate);
+  return pathFromRoot === "" || (pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep}`) && !isAbsolute(pathFromRoot));
+}
+
+export async function replaceArtifact(
+  active: ActiveSpace,
+  request: ArtifactReplacementRequest,
+): Promise<KnowledgeResult<ArtifactReplacementResult>> {
+  if (!isAbsolute(request.root)) {
+    return { ok: false, errors: [artifactError("artifact_root_invalid", "root must be an absolute path", "root")] };
+  }
+  const segments = request.relativePath.split("/");
+  if (
+    request.relativePath.length === 0 ||
+    request.relativePath.includes("\\") ||
+    request.relativePath.includes("\u0000") ||
+    segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")
+  ) {
+    return {
+      ok: false,
+      errors: [artifactError(
+        "relative_path_invalid",
+        "relativePath must be a normalized relative path without .., ., empty, backslash, or NUL segments",
+        "relativePath",
+      )],
+    };
+  }
+
+  // Canonicalize the requested root before any comparison: every containment
+  // decision below compares real paths so a symlinked path component cannot
+  // make two locations that are the same directory compare unequal — or two
+  // different directories compare equal.
+  let rootReal: string;
+  try {
+    rootReal = await realpath(request.root);
+  } catch (error) {
+    return {
+      ok: false,
+      errors: [artifactError("artifact_root_unavailable", `root could not be resolved: ${error instanceof Error ? error.message : String(error)}`, "root")],
+    };
+  }
+  if (!(await stat(rootReal)).isDirectory()) {
+    return { ok: false, errors: [artifactError("artifact_root_invalid", "root must name a directory", "root")] };
+  }
+
+  // The requested root is configuration; the binding authorizes it.
+  if (!active.writeRoots.some((writeRoot) => containsPath(writeRoot, rootReal))) {
+    return {
+      ok: false,
+      errors: [artifactError("root_not_writable", `requested artifact root is not inside an active write root: ${request.root}`, "root")],
+    };
+  }
+  if (!containsPath(active.spaceRoot, rootReal)) {
+    return {
+      ok: false,
+      errors: [artifactError("root_outside_space", `requested artifact root is outside the active space root: ${request.root}`, "root")],
+    };
+  }
+
+  // Resolve the deepest existing ancestor lexically, then realpath it: if any
+  // existing ancestor is a symlink, its resolved location must still be inside
+  // the canonicalized root. New (not-yet-existing) trailing components are
+  // appended under that resolved location.
+  const dirSegments = segments.slice(0, -1);
+  const fileName = requireSegment(segments, segments.length - 1);
+  let existingCount = 0;
+  let ancestor = rootReal;
+  while (existingCount < dirSegments.length) {
+    const next = join(ancestor, requireSegment(dirSegments, existingCount));
+    try {
+      await lstat(next);
+    } catch {
+      break;
+    }
+    ancestor = next;
+    existingCount++;
+  }
+  let ancestorReal: string;
+  try {
+    ancestorReal = await realpath(ancestor);
+  } catch (error) {
+    return {
+      ok: false,
+      errors: [artifactError("parent_resolution_failed", `parent directory could not be resolved: ${error instanceof Error ? error.message : String(error)}`, "relativePath")],
+    };
+  }
+  if (!containsPath(rootReal, ancestorReal)) {
+    return {
+      ok: false,
+      errors: [artifactError("parent_escape", `a parent directory resolves outside the requested artifact root: ${request.root}/${request.relativePath}`, "relativePath")],
+    };
+  }
+
+  const targetPath = join(ancestorReal, ...dirSegments.slice(existingCount), fileName);
+
+  // Refuse a symlinked target outright: replacement means "these bytes at this
+  // path", never "follow this link and clobber whatever it names".
+  try {
+    const targetStat = await lstat(targetPath);
+    if (targetStat.isSymbolicLink()) {
+      return {
+        ok: false,
+        errors: [artifactError("target_symlink", `target path is a symbolic link and will not be written through: ${request.relativePath}`, "relativePath")],
+      };
+    }
+  } catch (error) {
+    if (!isMissing(error)) {
+      return {
+        ok: false,
+        errors: [artifactError("target_stat_failed", `target could not be inspected: ${error instanceof Error ? error.message : String(error)}`, "relativePath")],
+      };
+    }
+  }
+
+  let current: string | undefined;
+  try {
+    current = await readFile(targetPath, "utf8");
+  } catch (error) {
+    if (!isMissing(error)) {
+      return {
+        ok: false,
+        errors: [artifactError("current_read_failed", `current artifact bytes could not be read: ${error instanceof Error ? error.message : String(error)}`, "relativePath")],
+      };
+    }
+  }
+  if (current === request.content) {
+    return { ok: true, value: { status: "unchanged", path: displayPath(request.root, segments) } };
+  }
+
+  // Materialized views live in nested paths that may not exist yet; the
+  // confinement checks above already validated every existing ancestor, so
+  // creating the remaining directories under the resolved location is safe.
+  try {
+    await mkdir(dirname(targetPath), { recursive: true });
+  } catch (error) {
+    return {
+      ok: false,
+      errors: [artifactError("parent_create_failed", `parent directory could not be created: ${error instanceof Error ? error.message : String(error)}`, "relativePath")],
+    };
+  }
+
+  try {
+    await atomicWriteFile(targetPath, request.content);
+  } catch (error) {
+    return {
+      ok: false,
+      errors: [artifactError("artifact_write_failed", `atomic artifact write failed; previous bytes are untouched: ${error instanceof Error ? error.message : String(error)}`, "relativePath")],
+    };
+  }
+  return { ok: true, value: { status: "replaced", path: displayPath(request.root, segments) } };
+}
+
+function requireSegment(segments: readonly string[], index: number): string {
+  const segment = segments[index];
+  if (segment === undefined) throw new Error(`internal invariant violated: segment ${index} must exist within relativePath`);
+  return segment;
+}
+
+// The reported path mirrors the caller's spelling (requested root + relative
+// path), not the internal resolved location: confinement decisions used real
+// paths, but the caller asked about this path.
+function displayPath(root: string, segments: readonly string[]): string {
+  return resolve(root, ...segments);
+}

package/src/captureTypes.ts

@@ -0,0 +1,31 @@
+// Public host-capture DTOs shared between the OMP adapter and external packs.
+// JSON-safe by construction: these shapes cross process boundaries verbatim,
+// so they deliberately carry no functions, classes, or host handles.
+
+import type { JsonObject, KnowledgeError, KnowledgeRecord } from "./knowledgeTypes.ts";
+
+export type CaptureMutationView = {
+  recordId: string;
+  action: "create" | "update";
+  beforeHash: string | null;
+  after: KnowledgeRecord;
+};
+
+export type HostCapturePreview =
+  | { schemaVersion: 0; status: "ready"; planHash: string; mutations: CaptureMutationView[] }
+  | { schemaVersion: 0; status: "blocked"; errors: KnowledgeError[] };
+
+export type HostCaptureApply = {
+  schemaVersion: 0;
+  status: "committed" | "no-change" | "stale" | "failed";
+  planHash: string;
+  mutations: CaptureMutationView[];
+  index: "fresh" | "stale" | "not-attempted";
+  errors: string[];
+};
+
+export type ArtifactReplacementResult = { status: "replaced" | "unchanged"; path: string };
+
+export type CompletionRequest = { model: string; prompt: string; system: string; timeoutSeconds: number };
+
+export type CaptureChangeSetInput = JsonObject;

package/src/cli.ts

@@ -11,6 +11,7 @@
 //   engram space register --binding <path-to-local-binding.json>
 //   engram space select <space-id>
 //   engram space status
+//   engram space refresh
 //   engram recall --query <text> --audience <id>
 //   engram version
 //
@@ -42,10 +43,10 @@ import {
   type ActiveSpace,
 } from "./spaceRegistry.ts";
 import { submitCandidate, type SubmitOutcome } from "./submit.ts";
-import { REFRESH_NOT_ATTEMPTED } from "./qmdRunner.ts";
+import { refreshQmdCollection, REFRESH_NOT_ATTEMPTED } from "./qmdRunner.ts";
 import { guardedRetrieve } from "./guardedRetrieval.ts";
 import { renderPresentation } from "./presentation.ts";
-import type { KnowledgePack, KnowledgeExtractor, PresentationPack, TurnContext, TurnToolCall, PackHelpers } from "./knowledgeTypes.ts";
+import { KNOWLEDGE_STATUSES, type KnowledgePack, type KnowledgeExtractor, type KnowledgeStatus, type PresentationPack, type TurnContext, type TurnToolCall, type PackHelpers } from "./knowledgeTypes.ts";
 import { loadExtractionPack, resolveKnowledgePack } from "./packLoader.ts";
 import { requireDefined } from "./types.ts";
 import {
@@ -55,6 +56,8 @@ import {
   type ApplyKnowledgeOutcome,
 } from "./knowledgeTransaction.ts";
 import { approveKnowledgeRollup, previewKnowledgeRollup, type KnowledgeRollupApplyOutcome } from "./knowledgeRollup.ts";
+import { listKnowledgeRecords } from "./knowledgeListing.ts";
+import { replaceArtifact } from "./artifactReplacement.ts";
 import { readReleaseManifest } from "../release/engram-release.ts";
 
 function printJson(value: unknown): void {
@@ -66,13 +69,16 @@ const USAGE = [
   "       engram knowledge submit --candidate <path>",
   "       engram knowledge reconcile --candidate <path>",
   "       engram knowledge approve|reject --candidate <path> --expect <plan_hash>",
+  "       engram knowledge list --pack <id> --status <status> [--status <status> ...]",
   "       engram rollup preview --bullets <path>",
   "       engram rollup approve --bullets <path> --expect <rollup-hash>",
   "       engram space register --binding <path>",
   "       engram space select <space-id>",
   "       engram space status",
+  "       engram space refresh",
   "       engram recall --query <text> --audience <id> [--source-class <class>]",
   "       engram render --view <id> --audience <id> --delivery <id> --model <provider/model> [--query <text>]",
+  "       engram artifact replace --root <absolute-root> --relative <path> --input <file>",
 ].join("\n");
 
 function usageError(message: string): never {
@@ -163,6 +169,23 @@ async function runSpaceCommand(args: string[]): Promise<void> {
     printJson(result.value);
     return;
   }
+  if (subcommand === "refresh") {
+    if (rest.length !== 0) usageError("space refresh accepts no arguments");
+    const registry = registryPath();
+    const active = await resolveActiveSpace(process.env);
+    if (!active.ok) printInvalid(active.errors);
+    const refresh = await refreshQmdCollection(active.value);
+    const recorded = await recordQmdFreshness(registry, active.value.spaceId, refresh.state);
+    const output = {
+      schema_version: 0,
+      status: refresh.state === "fresh" ? "refreshed" : "index-stale",
+      refresh,
+      ...(recorded.ok ? {} : { status_warnings: recorded.errors }),
+    };
+    printJson(output);
+    if (refresh.state !== "fresh") process.exit(1);
+    return;
+  }
   usageError(`unknown space command: ${subcommand ?? "(none)"}`);
 }
 
@@ -280,6 +303,31 @@ function knowledgeArgs(rest: string[]): { candidatePath: string; expectHash?: st
   return { candidatePath, ...(expectHash === undefined ? {} : { expectHash }) };
 }
 
+function knowledgeListArgs(rest: string[]): { packId: string; statuses: KnowledgeStatus[] } {
+  let packId: string | undefined;
+  const statuses: KnowledgeStatus[] = [];
+  for (let index = 0; index < rest.length; index++) {
+    const arg = rest[index];
+    if (arg === "--pack") {
+      index++;
+      packId = rest[index];
+      if (packId === undefined) usageError("--pack requires a value");
+    } else if (arg === "--status") {
+      index++;
+      const rawStatus = rest[index];
+      if (rawStatus === undefined) usageError("--status requires a value");
+      const status = KNOWLEDGE_STATUSES.find((candidate) => candidate === rawStatus);
+      if (status === undefined) usageError(`--status must be one of ${KNOWLEDGE_STATUSES.join(", ")}`);
+      statuses.push(status);
+    } else {
+      usageError(`unrecognized argument: ${arg}`);
+    }
+  }
+  if (packId === undefined) usageError("knowledge list requires --pack <id>");
+  if (statuses.length === 0) usageError("knowledge list requires at least one --status <status>");
+  return { packId, statuses };
+}
+
 function knowledgeExit(outcome: ApplyKnowledgeOutcome): never {
   if (outcome.status === "committed" || outcome.status === "rejected" || outcome.status === "no_change") process.exit(0);
   if (outcome.status === "stale_approval") process.exit(3);
@@ -287,8 +335,28 @@ function knowledgeExit(outcome: ApplyKnowledgeOutcome): never {
   process.exit(1);
 }
 
+async function runKnowledgeListCommand(rest: string[]): Promise<void> {
+  const parsed = knowledgeListArgs(rest);
+  const bindingResult = await resolveActiveSpace(process.env);
+  if (!bindingResult.ok) {
+    printJson({ schema_version: 0, status: "invalid", errors: bindingResult.errors });
+    process.exit(1);
+  }
+  const result = await listKnowledgeRecords(bindingResult.value, parsed);
+  if (!result.ok) {
+    printJson({ schema_version: 0, status: "invalid", errors: result.errors });
+    process.exit(1);
+  }
+  printJson({ schema_version: 0, status: "ok", records: result.value });
+  process.exit(0);
+}
+
 async function runKnowledgeCommand(args: string[]): Promise<void> {
   const [subcommand, ...rest] = args;
+  if (subcommand === "list") {
+    await runKnowledgeListCommand(rest);
+    return;
+  }
   if (subcommand !== "submit" && subcommand !== "reconcile" && subcommand !== "approve" && subcommand !== "reject") {
     usageError(`unknown knowledge command: ${subcommand ?? "(none)"}`);
   }
@@ -662,6 +730,74 @@ async function runVersionCommand(): Promise<void> {
   });
 }
 
+function artifactReplaceArgs(rest: string[]): { root: string; relativePath: string; inputPath: string } {
+  let root: string | undefined;
+  let relativePath: string | undefined;
+  let inputPath: string | undefined;
+  for (let index = 0; index < rest.length; index++) {
+    const arg = rest[index];
+    if (arg === "--root") {
+      index++;
+      root = rest[index];
+      if (root === undefined) usageError("--root requires a value");
+    } else if (arg === "--relative") {
+      index++;
+      relativePath = rest[index];
+      if (relativePath === undefined) usageError("--relative requires a value");
+    } else if (arg === "--input") {
+      index++;
+      inputPath = rest[index];
+      if (inputPath === undefined) usageError("--input requires a value");
+    } else {
+      usageError(`unrecognized argument: ${arg}`);
+    }
+  }
+  if (root === undefined) usageError("artifact replace requires --root <absolute-root>");
+  if (!isAbsolute(root)) usageError("--root must be an absolute path");
+  if (relativePath === undefined) usageError("artifact replace requires --relative <path>");
+  if (inputPath === undefined) usageError("artifact replace requires --input <file>");
+  return { root, relativePath, inputPath };
+}
+
+async function runArtifactReplaceCommand(rest: string[]): Promise<void> {
+  const parsed = artifactReplaceArgs(rest);
+  const bindingResult = await resolveActiveSpace(process.env);
+  if (!bindingResult.ok) {
+    printJson({ schema_version: 0, status: "invalid", errors: bindingResult.errors });
+    process.exit(1);
+  }
+  let content: string;
+  try {
+    content = await readFile(parsed.inputPath, "utf8");
+  } catch (error) {
+    printJson({
+      schema_version: 0,
+      status: "invalid",
+      errors: [`failed to read --input file: ${error instanceof Error ? error.message : String(error)}`],
+    });
+    process.exit(1);
+  }
+  const result = await replaceArtifact(bindingResult.value, {
+    root: parsed.root,
+    relativePath: parsed.relativePath,
+    content,
+  });
+  if (!result.ok) {
+    printJson({ schema_version: 0, status: "invalid", errors: result.errors });
+    process.exit(1);
+  }
+  printJson({ schema_version: 0, status: result.value.status, path: result.value.path });
+  process.exit(0);
+}
+
+async function runArtifactCommand(args: string[]): Promise<void> {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== "replace") {
+    usageError(`unknown artifact command: ${subcommand ?? "(none)"}`);
+  }
+  await runArtifactReplaceCommand(rest);
+}
+
 async function main(): Promise<void> {
   const [command, ...rest] = process.argv.slice(2);
   if (command === "space") {
@@ -692,6 +828,10 @@ async function main(): Promise<void> {
     await runCaptureFromTurnCommand(rest);
     return;
   }
+  if (command === "artifact") {
+    await runArtifactCommand(rest);
+    return;
+  }
   if (command === "version") {
     await runVersionCommand();
     return;

package/src/knowledgeListing.ts

@@ -0,0 +1,80 @@
+// Guarded record listing: a host mechanic for capture materialization that
+// enumerates the active space's records root and filters exactly, in memory,
+// by pack id and status.
+//
+// Two invariants shape this module:
+//
+// 1. The filesystem guard is shared, not reimplemented. Enumeration goes
+//    through retrieveEnumeratedRecords — the same candidate-guard sequence
+//    (`safeRelativeMarkdownPath` containment + realpath checks) guarded
+//    search uses — so a symlink escaping the records root FAILS the listing
+//    with a path_escape error rather than being silently skipped or followed.
+//    No qmd process is ever spawned: enumeration reads the records root
+//    directly.
+// 2. No caller-supplied filesystem root exists in the interface. The only
+//    root involved is the active space's bound recordsRoot; the filter is
+//    pack id + statuses, both evaluated exactly against parsed records.
+
+import { retrieveEnumeratedRecords, type GuardedRetrievalFilter } from "./knowledgeRetrieval.ts";
+import type { ActiveSpace } from "./spaceRegistry.ts";
+import type { KnowledgeError, KnowledgeRecord, KnowledgeResult } from "./knowledgeTypes.ts";
+
+export type KnowledgeListingFilter = {
+  packId: string;
+  statuses: readonly KnowledgeRecord["status"][];
+};
+
+// The listing is a host mechanic, not an audience-scoped view: materialization
+// needs every record of a pack regardless of which audience could see it. The
+// retrieval filter below is therefore a permissive host policy whose only real
+// work is routing every record through the shared containment guards; source
+// classification collapses to one host class so no record is dropped for
+// having a class the pack's presentation policy would withhold.
+const HOST_SOURCE_CLASS = "record";
+
+function hostListingRetrievalFilter(): GuardedRetrievalFilter {
+  return {
+    audienceId: "host-record-listing",
+    requestedSourceClasses: [HOST_SOURCE_CLASS],
+    allowedSourceClasses: [HOST_SOURCE_CLASS],
+    includePresentations: false,
+    relevanceThreshold: null,
+    classifySource: () => HOST_SOURCE_CLASS,
+    isEligible: () => true,
+    authorize: () => true,
+  };
+}
+
+function listingError(code: string, message: string, field?: string): KnowledgeError {
+  return field === undefined
+    ? { kind: "validation", code, message }
+    : { kind: "validation", code, field, message };
+}
+
+export async function listKnowledgeRecords(
+  active: ActiveSpace,
+  filter: KnowledgeListingFilter,
+): Promise<KnowledgeResult<KnowledgeRecord[]>> {
+  if (typeof filter.packId !== "string" || filter.packId.length === 0) {
+    return {
+      ok: false,
+      errors: [listingError("listing_filter_invalid", "packId must be a non-empty string", "packId")],
+    };
+  }
+  if (!Array.isArray(filter.statuses) || filter.statuses.length === 0) {
+    return {
+      ok: false,
+      errors: [listingError("listing_filter_invalid", "statuses must be a non-empty array", "statuses")],
+    };
+  }
+
+  const outcome = await retrieveEnumeratedRecords(active, hostListingRetrievalFilter());
+  if (outcome.kind === "failure") return { ok: false, errors: outcome.errors };
+
+  const records = outcome.records
+    .map((related) => related.record)
+    .filter((record) => record.pack.id === filter.packId && filter.statuses.includes(record.status))
+    // Deterministic ordering by record id regardless of directory-read order.
+    .sort((left, right) => left.id.localeCompare(right.id));
+  return { ok: true, value: records };
+}

package/src/knowledgeRetrieval.ts

@@ -472,6 +472,49 @@ export async function retrieveEnumeratedRecords(
   };
 }
 
+// Builds the receipt for an exact related-record enumeration. Enumeration
+// never ranks and runs no query, so `query` stays null and
+// `relevanceThreshold` stays null regardless of any pack-declared search
+// threshold; locators inherit the deterministic filename order
+// `enumerateCandidates` produced, and only the matched record IDs appear.
+function receiptForEnumeratedRecords(
+  binding: ActiveSpace,
+  matched: readonly RelatedKnowledgeRecord[],
+  withheldCount: number,
+): RetrievalReceipt {
+  const base = emptyReceipt(binding, null, matched.length === 0 ? "miss" : "hit", "space");
+  return withheldReceipt(
+    { ...base, locatorUris: matched.map((item) => item.sourceUri), recordIds: matched.map((item) => item.record.id) },
+    withheldCount,
+  );
+}
+
+// Exact related-record discovery for pack reconciliation: enumerates the
+// active records root directly (zero qmd invocations — see
+// `enumerateCandidates`), passes every candidate through the SAME
+// containment/parser guard sequence a search hit would face
+// (`filterCandidates` with no policy filter and no score threshold, because
+// enumeration never ranks), and only then applies the pack-owned predicate
+// to fully parsed records. A symlink escaping the root fails closed here
+// exactly as it does for search: the predicate can never observe an
+// uncontained or unparseable locator.
+export async function retrieveExactRelatedRecords(
+  binding: ActiveSpace,
+  matches: (record: KnowledgeRecord) => boolean,
+): Promise<RetrievalOutcome> {
+  const enumerated = await enumerateCandidates(binding);
+  if (enumerated.kind === "failure") {
+    return { kind: "failure", errors: [enumerated.error], receipt: emptyReceipt(binding, null, "miss", "space") };
+  }
+  const guarded = await filterCandidates(binding, enumerated.candidates, undefined, false);
+  if (guarded.kind === "failure") {
+    return { kind: "failure", errors: [guarded.error], receipt: emptyReceipt(binding, null, "miss", "space") };
+  }
+  const matched = guarded.records.filter((item) => matches(item.record));
+  const receipt = receiptForEnumeratedRecords(binding, matched, guarded.withheldCount);
+  return matched.length === 0 ? { kind: "miss", records: [], receipt } : { kind: "hit", records: matched, receipt };
+}
+
 async function retrieveRecords(
   binding: ActiveSpace,
   query: string,

package/src/knowledgeTransaction.ts

@@ -4,7 +4,7 @@ import { relative, resolve, sep } from "node:path";
 import { atomicWriteFile, AtomicWriteDirectorySyncError } from "./atomicWrite.ts";
 import { canonicalJson, hashKnowledgeText, parseKnowledgeRecord, serializeKnowledgeRecord } from "./knowledgeRecord.ts";
 import { validateKnowledgeEnvelope } from "./knowledgeValidation.ts";
-import { retrieveRelatedRecords, type RetrievalReceipt } from "./knowledgeRetrieval.ts";
+import { retrieveExactRelatedRecords, retrieveRelatedRecords, type RetrievalOutcome, type RetrievalReceipt } from "./knowledgeRetrieval.ts";
 import { acquireTransactionLock, transactionLockDirectory, type TransactionLock, type TransactionLockHooks } from "./transactionLock.ts";
 import { REFRESH_NOT_ATTEMPTED, refreshQmdCollection, type AttemptedRefreshReport, type RefreshReport, type SpawnFn } from "./qmdRunner.ts";
 import { resolveRecordPath } from "./spaceBinding.ts";
@@ -466,11 +466,20 @@ export async function reconcileKnowledgeTransaction(input: {
 }): Promise<ReconcileOutcome> {
   const candidateResult = prepareCandidate(input.binding, input.candidateInput, input.pack);
   if (!candidateResult.ok) return invalidOutcome(candidateResult.errors);
-  const query = input.pack.relatedQuery(candidateResult.value);
-  if (typeof query !== "string" || query.trim().length === 0 || /[\r\n]/.test(query)) {
-    return invalidOutcome([validationError("query_invalid", "pack retrieval query must be a non-empty single-line string")]);
+  const selection = input.pack.selectRelatedRecords(candidateResult.value);
+  let retrieval: RetrievalOutcome;
+  if (selection.mode === "search") {
+    const query = selection.query;
+    if (typeof query !== "string" || query.trim().length === 0 || /[\r\n]/.test(query)) {
+      return invalidOutcome([validationError("query_invalid", "pack retrieval query must be a non-empty single-line string")]);
+    }
+    retrieval = await retrieveRelatedRecords(input.binding, query, input.spawnFn);
+  } else {
+    // Exact mode changes related-record discovery only: qmd is never invoked
+    // and the authoritative re-read plus beforeHash capture below still apply
+    // to every returned record.
+    retrieval = await retrieveExactRelatedRecords(input.binding, selection.matches);
   }
-  const retrieval = await retrieveRelatedRecords(input.binding, query, input.spawnFn);
   if (retrieval.kind === "failure") return { schema_version: 0, status: "retrieval_failed", errors: retrieval.errors, retrieval: retrieval.receipt };
   const relatedRecords = retrieval.kind === "hit" ? retrieval.records : [];
   if (input.afterRetrieval !== undefined) await input.afterRetrieval();

package/src/knowledgeTypes.ts

@@ -121,11 +121,19 @@ export type PackReconciliation = {
   mutations: PackMutation[];
 };
 
+export type RelatedRecordSelection =
+  | { mode: "search"; query: string }
+  | {
+      mode: "exact";
+      description: string;
+      matches: (record: KnowledgeRecord) => boolean;
+    };
+
 export type KnowledgePack = {
   id: string;
   version: string;
   validateEnvelope: (envelope: KnowledgeEnvelope) => KnowledgeResult<void>;
-  relatedQuery: (envelope: KnowledgeEnvelope) => string;
+  selectRelatedRecords: (envelope: KnowledgeEnvelope) => RelatedRecordSelection;
   reconcile: (input: PackReconcileInput) => KnowledgeResult<PackReconciliation>;
 };
 

package/src/knowledgeValidation.ts

@@ -41,20 +41,6 @@ function isJsonValue(value: unknown): value is JsonValue {
   return Object.values(value).every((item) => isJsonValue(item));
 }
 
-function findNewline(value: JsonValue, field: string, errors: KnowledgeError[]): void {
-  if (typeof value === "string") {
-    if (/[\r\n]/.test(value)) errors.push(error("newline_forbidden", `${field} must not contain newlines`, field));
-    return;
-  }
-  if (Array.isArray(value)) {
-    value.forEach((item, index) => findNewline(item, `${field}[${index}]`, errors));
-    return;
-  }
-  if (value !== null && typeof value === "object") {
-    for (const [key, item] of Object.entries(value)) findNewline(item, `${field}.${key}`, errors);
-  }
-}
-
 function nonEmptySingleLine(value: unknown, field: string, errors: KnowledgeError[], pattern?: RegExp): string | undefined {
   if (typeof value !== "string" || value.trim().length === 0) {
     errors.push(error("field_invalid", `${field} must be a non-empty string`, field));
@@ -212,11 +198,8 @@ export function validateKnowledgeEnvelope(raw: unknown): KnowledgeResult<Knowled
       if (!isJsonValue(item)) validDetails = false;
       else parsedDetails[key] = item;
     }
-    if (!validDetails) errors.push(error("details_invalid", "details must be a JSON object", "details"));
-    else {
-      details = parsedDetails;
-      findNewline(details, "details", errors);
-    }
+    if (validDetails) details = parsedDetails;
+    else errors.push(error("details_invalid", "details must be a JSON object", "details"));
   }
 
   const scope = parseScope(raw.scope, errors);

package/src/packLoader.ts

@@ -92,7 +92,7 @@ function isKnowledgePack(value: unknown): value is KnowledgePack & PresentationP
     typeof value.id === "string" &&
     typeof value.version === "string" &&
     typeof value.validateEnvelope === "function" &&
-    typeof value.relatedQuery === "function" &&
+    typeof value.selectRelatedRecords === "function" &&
     typeof value.reconcile === "function" &&
     isSourceClassPolicy(value.retrievalPolicy) &&
     Array.isArray(value.views) && value.views.every(isView) &&