@isparling/engram-cli 0.1.0

package/src/contentHash.ts

@@ -0,0 +1,54 @@
+// Content hashing used to detect record changes across preview, approval, and
+// commit.
+//
+// Binds an `approval_required` result to the exact MUTATION the caller saw,
+// not merely to the record it started from.
+//
+// Hashing the record alone is insufficient and was a real defect: it detects
+// that the record changed under the caller, but it does not detect that the
+// caller approved a DIFFERENT mutation. With a record-only hash, previewing
+// candidate A against an unchanged record and then approving candidate B
+// with A's hash commits B — a diff the caller never saw. The submission date
+// has the same effect, since it changes the plan without touching the record.
+//
+// `hashPlan` therefore covers both endpoints of the diff: the exact bytes
+// read and the exact bytes that would be written.
+
+import { createHash } from "node:crypto";
+
+export function hashRecordText(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/**
+ * Hashes the complete mutation: where it lands, the record as read, and the
+ * text that would replace it. Any change to any of the three — a different
+ * destination, a modified record, a different candidate, or a submission date
+ * that alters the result — produces a different hash, so an approval cannot
+ * carry across to another mutation.
+ *
+ * The destination is included because before/after text alone is not a unique
+ * mutation: two spaces holding byte-identical records make the same textual
+ * transition, so a hash previewed in one space would otherwise approve the
+ * commit in another after a binding change.
+ *
+ * The record is hashed as raw bytes rather than decoded text. Decoding first
+ * maps every invalid UTF-8 sequence to U+FFFD, so distinct byte-level edits
+ * would collide and an intervening change could commit instead of being
+ * refused as stale.
+ *
+ * Components are length-prefixed so no triple can collide with a different
+ * triple through concatenation.
+ */
+export function hashPlan(recordPath: string, recordBytes: Buffer, afterText: string): string {
+  const after = Buffer.from(afterText, "utf8");
+  const destination = Buffer.from(recordPath, "utf8");
+  return createHash("sha256")
+    .update(`${destination.length}\n`)
+    .update(destination)
+    .update(`\n${recordBytes.length}\n`)
+    .update(recordBytes)
+    .update(`\n${after.length}\n`)
+    .update(after)
+    .digest("hex");
+}

package/src/deepFreeze.ts

@@ -0,0 +1,13 @@
+// Shared deep-freeze. Two call sites (knowledgeRetrieval.ts and
+// presentation.ts) used to carry verbatim copies of this without a seen-set,
+// so a self-referential object graph would recurse forever. Not reachable
+// from parseKnowledgeRecord output today, but worth one implementation with
+// cycle protection before anything else starts feeding it.
+export function deepFreeze<T>(value: T, seen: WeakSet<object> = new WeakSet()): T {
+  if (typeof value !== "object" || value === null) return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  if (!Object.isFrozen(value)) Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child, seen);
+  return value;
+}

package/src/diff.ts

@@ -0,0 +1,81 @@
+// Structural diff helpers for comparing knowledge records before they are
+// written.
+//
+// Small hand-written line-based diff (classic LCS dynamic program). Record
+// files are tiny (tens of lines), so the O(n*m) table is not a concern.
+// Renders the complete before/after text as a unified-style diff — this is
+// the "render the complete diff" step, used both to gate approval and to
+// show the reviewer exactly what a write will do.
+
+import { requireDefined } from "./types.ts";
+
+export type DiffOp = { type: "equal" | "add" | "remove"; line: string };
+
+/** Reads the LCS table at [i][j]. Every call site keeps i, j within
+ * [0, n] / [0, m] by construction, so an out-of-range read here would
+ * indicate a bug in the loop bounds, not a legitimate "no value" case —
+ * hence the thrown default instead of a silent `?? 0`. */
+function lcsAt(table: number[][], i: number, j: number): number {
+  const row = requireDefined(table[i], `lcs table row ${i} out of range`);
+  return requireDefined(row[j], `lcs table cell [${i}][${j}] out of range`);
+}
+
+function lineAt(lines: string[], i: number): string {
+  return requireDefined(lines[i], `line index ${i} out of range`);
+}
+
+export function diffLines(before: string[], after: string[]): DiffOp[] {
+  const n = before.length;
+  const m = after.length;
+  const lcs: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      const row = requireDefined(lcs[i], `lcs table row ${i} out of range`);
+      if (before[i] === after[j]) {
+        row[j] = lcsAt(lcs, i + 1, j + 1) + 1;
+      } else {
+        row[j] = Math.max(lcsAt(lcs, i + 1, j), lcsAt(lcs, i, j + 1));
+      }
+    }
+  }
+
+  const ops: DiffOp[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (before[i] === after[j]) {
+      ops.push({ type: "equal", line: lineAt(before, i) });
+      i++;
+      j++;
+    } else if (lcsAt(lcs, i + 1, j) >= lcsAt(lcs, i, j + 1)) {
+      ops.push({ type: "remove", line: lineAt(before, i) });
+      i++;
+    } else {
+      ops.push({ type: "add", line: lineAt(after, j) });
+      j++;
+    }
+  }
+  while (i < n) {
+    ops.push({ type: "remove", line: lineAt(before, i) });
+    i++;
+  }
+  while (j < m) {
+    ops.push({ type: "add", line: lineAt(after, j) });
+    j++;
+  }
+  return ops;
+}
+
+export function renderUnifiedDiff(recordId: string, beforeText: string, afterText: string): string {
+  const before = beforeText.split("\n");
+  const after = afterText.split("\n");
+  const ops = diffLines(before, after);
+
+  const lines: string[] = [`--- ${recordId} (before)`, `+++ ${recordId} (after)`];
+  for (const op of ops) {
+    const prefix = op.type === "equal" ? " " : op.type === "add" ? "+" : "-";
+    lines.push(`${prefix}${op.line}`);
+  }
+  return lines.join("\n");
+}

package/src/guardedRetrieval.ts

@@ -0,0 +1,128 @@
+import { guardedRetrieveInActiveSpace, receiptFor } from "./guardedRetrievalInternal.ts";
+import type { RetrievalReceipt } from "./knowledgeRetrieval.ts";
+import type { SpawnFn } from "./qmdRunner.ts";
+import { resolveActiveSpace, type ActiveSpace } from "./spaceRegistry.ts";
+import type { EnvLike, Result } from "./types.ts";
+import type {
+  KnowledgeError,
+  KnowledgeRecord,
+  PresentationPack,
+} from "./knowledgeTypes.ts";
+
+export type GuardedRetrievalRequest = {
+  query: string;
+  audienceId: string;
+  pack: PresentationPack;
+  viewId?: string;
+  requestedSourceClasses?: readonly string[];
+};
+
+// A space-scoped view's retrieval: enumerates every eligible record under
+// the active space's records root instead of running a ranked qmd search.
+// No `query` field — an enumerating view accepts no caller-supplied query
+// at all (see presentation.ts's `query_not_scoped` refusal).
+export type GuardedEnumerationRequest = {
+  audienceId: string;
+  pack: PresentationPack;
+  viewId?: string;
+  requestedSourceClasses?: readonly string[];
+};
+
+export type GuardedRetrievalRecord = {
+  record: KnowledgeRecord;
+  relativePath: string;
+  sourceUri: string;
+  sourceClasses: string[];
+  score?: number;
+};
+
+export type GuardedRetrievalHit = {
+  schema_version: 0;
+  status: "hit";
+  records: GuardedRetrievalRecord[];
+  receipt: RetrievalReceipt;
+};
+
+export type GuardedRetrievalMiss = {
+  schema_version: 0;
+  status: "miss";
+  records: [];
+  receipt: RetrievalReceipt;
+};
+
+export type GuardedRetrievalFailure = {
+  schema_version: 0;
+  status: "failed";
+  errors: KnowledgeError[];
+  receipt: RetrievalReceipt;
+};
+
+export type GuardedRetrievalOutcome = GuardedRetrievalHit | GuardedRetrievalMiss | GuardedRetrievalFailure;
+
+export type GuardedRetrievalOptions = {
+  env?: EnvLike;
+  spawnFn?: SpawnFn;
+};
+
+// A receipt for the "no active space" failure: guardedRetrieve cannot name
+// a space it never resolved, so this is a distinct type rather than a
+// fabricated ActiveSpace fed through the ordinary receipt shape.
+export type UnresolvedRetrievalReceipt = Omit<RetrievalReceipt, "activeSpace"> & { activeSpace: null };
+
+export type GuardedRetrievalUnresolvedFailure = {
+  schema_version: 0;
+  status: "failed";
+  errors: KnowledgeError[];
+  receipt: UnresolvedRetrievalReceipt;
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// Mirrors the defensiveness already applied to `request.query` below: this
+// runs before any pack validation, so `request.pack` cannot be trusted to
+// match its declared type at runtime.
+function allowedSourceClassesOf(pack: unknown): readonly string[] {
+  if (!isObject(pack)) return [];
+  const policy = pack.retrievalPolicy;
+  if (!isObject(policy)) return [];
+  const allowed = policy.allowedSourceClasses;
+  if (!Array.isArray(allowed)) return [];
+  return allowed.filter((entry): entry is string => typeof entry === "string");
+}
+
+export async function guardedRetrieve(
+  request: GuardedRetrievalRequest,
+  options: GuardedRetrievalOptions = {},
+): Promise<GuardedRetrievalOutcome | GuardedRetrievalUnresolvedFailure> {
+  const env = options.env ?? process.env;
+  const activeResult: Result<ActiveSpace> = await resolveActiveSpace(env);
+  if (!activeResult.ok) {
+    return {
+      schema_version: 0,
+      status: "failed",
+      errors: activeResult.errors.map((message) => ({ kind: "retrieval", code: "active_space_unresolved", message })),
+      receipt: receiptFor(
+        null,
+        typeof request.query === "string" ? request.query : null,
+        "search",
+        request.requestedSourceClasses === undefined ? [] : request.requestedSourceClasses,
+        allowedSourceClassesOf(request.pack),
+      ),
+    };
+  }
+  return guardedRetrieveInActiveSpace(activeResult.value, request, options);
+}
+
+export function isGuardedRetrievalHit(result: GuardedRetrievalOutcome): result is GuardedRetrievalHit {
+  return result.status === "hit";
+}
+
+export function isGuardedRetrievalMiss(result: GuardedRetrievalOutcome): result is GuardedRetrievalMiss {
+  return result.status === "miss";
+}
+
+export function isGuardedRetrievalFailure(result: GuardedRetrievalOutcome): result is GuardedRetrievalFailure {
+  return result.status === "failed";
+}

package/src/guardedRetrievalInternal.ts

@@ -0,0 +1,321 @@
+import {
+  retrieveEnumeratedRecords,
+  retrieveGuardedRecords,
+  type GuardedRetrievalFilter,
+  type RetrievalOutcome,
+  type RetrievalReceipt,
+} from "./knowledgeRetrieval.ts";
+import type { ActiveSpace } from "./spaceRegistry.ts";
+import type {
+  GuardedEnumerationRequest,
+  GuardedRetrievalFailure,
+  GuardedRetrievalOptions,
+  GuardedRetrievalOutcome,
+  GuardedRetrievalRecord,
+  GuardedRetrievalRequest,
+  UnresolvedRetrievalReceipt,
+} from "./guardedRetrieval.ts";
+import type { KnowledgeError, PresentationPack } from "./knowledgeTypes.ts";
+
+function retrievalError(code: string, message: string, field?: string): KnowledgeError {
+  return field === undefined
+    ? { kind: "retrieval", code, message }
+    : { kind: "retrieval", code, field, message };
+}
+
+export function receiptFor(
+  active: ActiveSpace,
+  query: string | null,
+  scope: "search" | "space",
+  requestedSourceClasses: readonly string[],
+  allowedSourceClasses: readonly string[],
+): RetrievalReceipt;
+export function receiptFor(
+  active: null,
+  query: string | null,
+  scope: "search" | "space",
+  requestedSourceClasses: readonly string[],
+  allowedSourceClasses: readonly string[],
+): UnresolvedRetrievalReceipt;
+export function receiptFor(
+  active: ActiveSpace | null,
+  query: string | null,
+  scope: "search" | "space",
+  requestedSourceClasses: readonly string[],
+  allowedSourceClasses: readonly string[],
+): RetrievalReceipt | UnresolvedRetrievalReceipt {
+  return {
+    schemaVersion: 0,
+    scope,
+    query,
+    activeSpace: active === null ? null : active.spaceId,
+    collection: active === null ? "" : active.qmdCollectionName,
+    requestedSourceClasses: [...requestedSourceClasses],
+    allowedSourceClasses: [...allowedSourceClasses],
+    kind: "miss",
+    locatorUris: [],
+    recordIds: [],
+    exposedResults: [],
+    // No filtering — let alone ranking — has run yet at any of this
+    // function's call sites (pack validation, installation, query shape,
+    // audience lookup, source-class authorization, or query-strategy
+    // failures, plus the "no active space" case handled by guardedRetrieve
+    // before any of the above even runs), so there is no threshold to report
+    // and no withholding to disclose.
+    relevanceThreshold: null,
+    withheld: { audienceId: null, count: 0 },
+  };
+}
+
+function failure(
+  active: ActiveSpace,
+  query: string | null,
+  scope: "search" | "space",
+  requestedSourceClasses: readonly string[],
+  allowedSourceClasses: readonly string[],
+  errors: KnowledgeError[],
+): GuardedRetrievalFailure {
+  return {
+    schema_version: 0,
+    status: "failed",
+    errors,
+    receipt: receiptFor(active, query, scope, requestedSourceClasses, allowedSourceClasses),
+  };
+}
+
+function activePackInstalled(active: ActiveSpace, pack: PresentationPack): boolean {
+  return active.packs.some((installed) => installed.id === pack.id && installed.version === pack.version);
+}
+
+function uniqueStrings(values: readonly string[]): string[] {
+  return [...new Set(values)];
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  return Array.isArray(value) && value.every((item) => typeof item === "string") ? [...value] : undefined;
+}
+
+function functionValue(value: unknown): Function | undefined {
+  return typeof value === "function" ? value : undefined;
+}
+
+type PolicySnapshot = {
+  allowedSourceClasses: string[];
+  queryStrategy: PresentationPack["retrievalPolicy"]["queryStrategy"];
+  classifySource: PresentationPack["retrievalPolicy"]["classifySource"];
+  relevanceThreshold: number | null;
+  isEligible: PresentationPack["retrievalPolicy"]["isEligible"];
+  includePresentations: unknown;
+};
+
+function snapshotPolicy(pack: unknown): { ok: true; value: PolicySnapshot } | { ok: false; allowedSourceClasses: string[]; errors: KnowledgeError[] } {
+  if (!isObject(pack) || !isObject(pack.retrievalPolicy)) {
+    return { ok: false, allowedSourceClasses: [], errors: [retrievalError("policy_shape_invalid", "retrieval policy must be an object", "pack")] };
+  }
+  const policy = pack.retrievalPolicy;
+  const allowedSourceClasses = stringArray(policy.allowedSourceClasses);
+  if (allowedSourceClasses === undefined) {
+    return { ok: false, allowedSourceClasses: [], errors: [retrievalError("policy_shape_invalid", "retrieval policy allowedSourceClasses must be an array of strings", "pack")] };
+  }
+  const queryStrategy = functionValue(policy.queryStrategy);
+  const classifySource = functionValue(policy.classifySource);
+  const isEligible = functionValue(policy.isEligible);
+  if (queryStrategy === undefined || classifySource === undefined || isEligible === undefined) {
+    return { ok: false, allowedSourceClasses, errors: [retrievalError("policy_shape_invalid", "retrieval policy callbacks must be functions", "pack")] };
+  }
+  if (policy.includePresentations !== false) {
+    return { ok: true, value: {
+      allowedSourceClasses,
+      queryStrategy: (input) => Reflect.apply(queryStrategy, undefined, [input]),
+      classifySource: (source) => Reflect.apply(classifySource, undefined, [source]),
+      relevanceThreshold: typeof policy.relevanceThreshold === "number" || policy.relevanceThreshold === null ? policy.relevanceThreshold : Number.NaN,
+      isEligible: (record) => Reflect.apply(isEligible, undefined, [record]),
+      includePresentations: policy.includePresentations,
+    } };
+  }
+  return { ok: true, value: {
+    allowedSourceClasses,
+    queryStrategy: (input) => Reflect.apply(queryStrategy, undefined, [input]),
+    classifySource: (source) => Reflect.apply(classifySource, undefined, [source]),
+    relevanceThreshold: typeof policy.relevanceThreshold === "number" || policy.relevanceThreshold === null ? policy.relevanceThreshold : Number.NaN,
+    isEligible: (record) => Reflect.apply(isEligible, undefined, [record]),
+    includePresentations: false,
+  } };
+}
+
+function validatePolicy(policy: PolicySnapshot): KnowledgeError[] {
+  const errors: KnowledgeError[] = [];
+  if (policy.includePresentations !== false) {
+    errors.push(retrievalError("policy_presentations_included", "retrieval policy must exclude presentation artifacts"));
+  }
+  if (policy.allowedSourceClasses.length === 0) {
+    errors.push(retrievalError("policy_source_classes_empty", "retrieval policy must declare at least one allowed source class"));
+  }
+  if (
+    policy.relevanceThreshold !== null &&
+    (!Number.isFinite(policy.relevanceThreshold) || policy.relevanceThreshold < 0)
+  ) {
+    errors.push(retrievalError("policy_relevance_threshold_invalid", "retrieval policy relevance threshold must be null or a non-negative finite number"));
+  }
+  return errors;
+}
+
+// "search" runs the pack's declared query strategy over a ranked qmd search;
+// "space" enumerates every Markdown record under the active space's records
+// root and runs no qmd process. Everything in `performRetrieval` below this
+// point — policy validation, pack installation, audience lookup, source-class
+// authorization — applies identically to both; only query construction and
+// the final retrieval call differ, so neither mode can silently skip a guard
+// the other one runs.
+type RetrievalMode =
+  | { kind: "search"; query: string }
+  | { kind: "space" };
+
+async function performRetrieval(
+  active: ActiveSpace,
+  mode: RetrievalMode,
+  request: GuardedEnumerationRequest,
+  options: GuardedRetrievalOptions,
+): Promise<GuardedRetrievalOutcome> {
+  const policySnapshot = snapshotPolicy(request.pack);
+  const baseQuery: string | null = mode.kind === "search" ? mode.query : null;
+  const scope = mode.kind;
+  const initialAllowedSourceClasses = policySnapshot.ok ? policySnapshot.value.allowedSourceClasses : policySnapshot.allowedSourceClasses;
+  const requestedSourceClasses = request.requestedSourceClasses === undefined
+    ? [...initialAllowedSourceClasses]
+    : uniqueStrings(request.requestedSourceClasses);
+  if (!policySnapshot.ok) {
+    return failure(active, baseQuery, scope, requestedSourceClasses, policySnapshot.allowedSourceClasses, policySnapshot.errors);
+  }
+  const policy = policySnapshot.value;
+
+  const packErrors = validatePolicy(policy);
+  if (packErrors.length > 0) {
+    return failure(active, baseQuery, scope, requestedSourceClasses, policy.allowedSourceClasses, packErrors);
+  }
+  if (!activePackInstalled(active, request.pack)) {
+    return failure(active, baseQuery, scope, requestedSourceClasses, policy.allowedSourceClasses, [retrievalError(
+      "pack_not_installed",
+      `presentation pack ${request.pack.id}@${request.pack.version} is not installed in the active space`,
+      "pack",
+    )]);
+  }
+  if (mode.kind === "search" && (typeof mode.query !== "string" || mode.query.trim().length === 0 || mode.query.includes("\u0000"))) {
+    return failure(active, baseQuery, scope, requestedSourceClasses, policy.allowedSourceClasses, [retrievalError(
+      "query_invalid",
+      "retrieval query must be a non-empty string without NUL bytes",
+      "query",
+    )]);
+  }
+  const audience = request.pack.audiences.find((candidate) => candidate.id === request.audienceId);
+  if (audience === undefined) {
+    return failure(active, baseQuery, scope, requestedSourceClasses, policy.allowedSourceClasses, [retrievalError(
+      "audience_unknown",
+      `audience ${request.audienceId} is not configured by the presentation pack`,
+      "audience",
+    )]);
+  }
+  const audienceSnapshot = Object.freeze({ id: audience.id, authorize: audience.authorize });
+  const disallowedRequestedClass = requestedSourceClasses.find(
+    (sourceClass) => !policy.allowedSourceClasses.includes(sourceClass),
+  );
+  if (disallowedRequestedClass !== undefined) {
+    return failure(active, baseQuery, scope, requestedSourceClasses, policy.allowedSourceClasses, [retrievalError(
+      "source_class_not_allowed",
+      `requested source class ${disallowedRequestedClass} is not allowed by the retrieval policy`,
+      "requestedSourceClasses",
+    )]);
+  }
+  if (requestedSourceClasses.length === 0) {
+    return {
+      schema_version: 0,
+      status: "miss",
+      records: [],
+      receipt: receiptFor(active, baseQuery, scope, requestedSourceClasses, policy.allowedSourceClasses),
+    };
+  }
+
+  const filter: GuardedRetrievalFilter = {
+    audienceId: audienceSnapshot.id,
+    requestedSourceClasses,
+    allowedSourceClasses: policy.allowedSourceClasses,
+    includePresentations: false,
+    relevanceThreshold: policy.relevanceThreshold,
+    classifySource: policy.classifySource,
+    isEligible: policy.isEligible,
+    authorize: audienceSnapshot.authorize,
+  };
+
+  let retrieval: RetrievalOutcome;
+  if (mode.kind === "search") {
+    let query: string;
+    try {
+      query = policy.queryStrategy({
+        query: mode.query,
+        ...(request.viewId === undefined ? {} : { viewId: request.viewId }),
+        requestedSourceClasses,
+      });
+    } catch (error) {
+      return failure(active, baseQuery, scope, requestedSourceClasses, policy.allowedSourceClasses, [retrievalError(
+        "query_strategy_failed",
+        `retrieval query strategy failed: ${error instanceof Error ? error.message : String(error)}`,
+      )]);
+    }
+    if (typeof query !== "string" || query.trim().length === 0 || query.includes("\u0000")) {
+      return failure(active, baseQuery, scope, requestedSourceClasses, policy.allowedSourceClasses, [retrievalError(
+        "query_strategy_invalid",
+        "retrieval query strategy returned an empty or unsafe query",
+      )]);
+    }
+    retrieval = await retrieveGuardedRecords(active, query, filter, options.spawnFn);
+  } else {
+    retrieval = await retrieveEnumeratedRecords(active, filter);
+  }
+
+  if (retrieval.kind === "failure") return { schema_version: 0, status: "failed", errors: retrieval.errors, receipt: retrieval.receipt };
+  if (retrieval.kind === "miss") return { schema_version: 0, status: "miss", records: [], receipt: retrieval.receipt };
+
+  const records: GuardedRetrievalRecord[] = [];
+  for (const related of retrieval.records) {
+    const exposed = retrieval.receipt.exposedResults.find((candidate) => candidate.recordId === related.record.id);
+    if (exposed === undefined) {
+      return failure(active, baseQuery, scope, requestedSourceClasses, policy.allowedSourceClasses, [retrievalError(
+        "receipt_incomplete",
+        "retrieval receipt did not contain a reference for every exposed record",
+      )]);
+    }
+    records.push({
+      record: related.record,
+      relativePath: related.relativePath,
+      sourceUri: related.sourceUri,
+      sourceClasses: [...exposed.sourceClasses],
+      ...(exposed.score === undefined ? {} : { score: exposed.score }),
+    });
+  }
+  return { schema_version: 0, status: "hit", records, receipt: retrieval.receipt };
+}
+
+export async function guardedRetrieveInActiveSpace(
+  active: ActiveSpace,
+  request: GuardedRetrievalRequest,
+  options: GuardedRetrievalOptions = {},
+): Promise<GuardedRetrievalOutcome> {
+  return performRetrieval(active, { kind: "search", query: request.query }, request, options);
+}
+
+// The space-scoped counterpart used only by `renderPresentation` when a
+// view's scope is "space": no query is ever constructed or validated, and
+// the final retrieval call enumerates the records root instead of running a
+// qmd search. Every other guard above is shared, unchanged, with
+// `guardedRetrieveInActiveSpace`.
+export async function guardedEnumerateInActiveSpace(
+  active: ActiveSpace,
+  request: GuardedEnumerationRequest,
+  options: GuardedRetrievalOptions = {},
+): Promise<GuardedRetrievalOutcome> {
+  return performRetrieval(active, { kind: "space" }, request, options);
+}