@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.1

package/src/memory.js

@@ -0,0 +1,552 @@
+import { createHash, randomUUID } from "node:crypto";
+import { isAbsolute, join, normalize, resolve } from "node:path";
+import { MemoryDatabase } from "./memory-sqlite.js";
+import { CODEFLOW_HOME } from "./config.js";
+const MAX_ENTRIES = 5e3;
+const MAX_RUN_ENTRIES = 512;
+const MAX_BODY = 16e3;
+const MAX_FILE = 32 * 1024 * 1024;
+const queues = /* @__PURE__ */ new Map();
+class MemoryConflictError extends Error {
+  constructor(current2) {
+    super(`Memory revision conflict: ${current2.id} is at revision ${current2.revision}`);
+    this.current = current2;
+    this.name = "MemoryConflictError";
+  }
+}
+class MemoryStore {
+  file;
+  database;
+  constructor(file = join(CODEFLOW_HOME, "memory.sqlite")) {
+    this.file = resolve(file.replace(/\.json$/, ".sqlite"));
+    this.database = new MemoryDatabase(this.file, validateDocument);
+  }
+  async load() {
+    await this.read();
+  }
+  async propose(raw, authority, options = {}) {
+    return this.change((doc) => {
+      const input = validateInput(raw);
+      if (authority.kind === "run" && input.scope === "project") input.runId ??= authority.runId;
+      authorize(input, authority, true);
+      const operationHash = hashOperation(input, authority);
+      if (input.operationId) {
+        const previous = doc.entries.find((e) => e.repo === input.repo && e.projectId === input.projectId && e.operationId === input.operationId);
+        if (previous) {
+          authorize(previous, authority, true);
+          if (previous.operationHash !== operationHash) throw new Error("Memory operation ID was already used for different content");
+          return clone(previous);
+        }
+      }
+      if (options.expectedSources !== void 0) {
+        const expected = uniqueRefs(options.expectedSources);
+        if (JSON.stringify(expected) !== JSON.stringify(input.derivedFrom ?? [])) throw new Error("Guarded publication must identify every derivation source");
+        for (const sourceRef of expected) {
+          const source = doc.entries.find((entry2) => entry2.id === sourceRef.id);
+          if (!source) throw new Error("Memory publication source does not exist");
+          authorize(source, authority, false);
+          if (source.status === "deleted" || source.revision !== sourceRef.revision || source.expiresAt !== void 0 && source.expiresAt <= Date.now() || source.feedback?.some((item) => item.revision === source.revision && (item.rating === "stale" || item.rating === "incorrect"))) throw new MemoryConflictError(clone(source));
+        }
+      }
+      const live = doc.entries.filter((entry2) => entry2.status !== "deleted");
+      if (input.scope === "project" && live.filter((entry2) => entry2.scope === "project").length >= MAX_ENTRIES) throw new Error("Memory limit reached; remove older records before adding more");
+      if (input.scope !== "project" && live.filter((entry2) => entry2.scope !== "project" && entry2.runId === input.runId).length >= MAX_RUN_ENTRIES) throw new Error(`This run has reached its limit of ${MAX_RUN_ENTRIES} private and team memory records`);
+      const sources = sourceEntries(doc, input.derivedFrom ?? [], input, authority);
+      const origins = unionOrigins([origin(authority, input.scope), ...sources.flatMap((e) => e.origins)]);
+      preventPrivatePublication(input.scope, origins, authority);
+      const now = Date.now();
+      const accepted = authority.kind === "user" || authority.kind === "run" && input.scope === "private";
+      const entry = {
+        ...input,
+        id: `m-${randomUUID()}`,
+        revision: 1,
+        status: accepted ? "accepted" : "proposed",
+        tags: input.tags ?? [],
+        paths: input.paths ?? [],
+        applicability: input.applicability ?? { kind: "repository" },
+        derivedFrom: input.derivedFrom ?? [],
+        sourceRefs: input.sourceRefs ?? [],
+        origins,
+        createdAt: now,
+        updatedAt: now,
+        ...accepted ? { acceptedBy: authority.kind === "user" ? "user" : "owner" } : {},
+        ...input.operationId ? { operationHash } : {}
+      };
+      doc.entries.push(entry);
+      return clone(entry);
+    });
+  }
+  async revise(id, expectedRevision, patch, authority, options = {}) {
+    return this.change((doc) => {
+      const entry = current(doc, id, expectedRevision, authority, true);
+      const input = validateInput({ ...entry, ...patch });
+      input.derivedFrom = uniqueRefs([...entry.derivedFrom, ...input.derivedFrom ?? []]);
+      if (input.derivedFrom.some((ref) => ref.id === entry.id)) throw new Error("Memory cannot derive from itself");
+      const added = input.derivedFrom.filter((ref) => !entry.derivedFrom.some((old) => old.id === ref.id && old.revision === ref.revision));
+      const sources = sourceEntries(doc, added, input, authority);
+      const origins = unionOrigins([...entry.origins, origin(authority, entry.scope), ...sources.flatMap((e) => e.origins)]);
+      preventPrivatePublication(entry.scope, origins, authority);
+      Object.assign(entry, input, { origins });
+      if ("expiresAt" in patch && patch.expiresAt === void 0) delete entry.expiresAt;
+      if (entry.scope === "private") {
+        entry.status = "accepted";
+        entry.acceptedBy = "owner";
+      } else if (authority.kind === "user") {
+        if (options.accept || entry.status === "accepted") {
+          entry.status = "accepted";
+          entry.acceptedBy = "user";
+        }
+      } else {
+        entry.status = "proposed";
+        entry.acceptedBy = void 0;
+      }
+      delete entry.verification;
+      touch(entry);
+      return clone(entry);
+    });
+  }
+  /** Approve this exact revision. Tainted project content always requires the user. */
+  async accept(id, expectedRevision, authority, verification, operationId) {
+    return this.change((doc) => {
+      const entry = doc.entries.find((candidate) => candidate.id === id);
+      if (!entry || entry.status === "deleted") throw new Error("Memory entry not found");
+      authorize(entry, authority, true);
+      const operation = operationId === void 0 ? void 0 : text(operationId, 500, "acceptance operation ID");
+      const fingerprint = createHash("sha256").update(canonicalJson({ expectedRevision, authority, verification })).digest("hex");
+      const previous = operation ? entry.acceptanceOperations?.find((saved) => saved.id === operation) : void 0;
+      if (previous) {
+        if (previous.fingerprint !== fingerprint) throw new Error("Memory acceptance operation ID was already used for a different approval");
+        if (entry.revision !== previous.resultRevision) throw new MemoryConflictError(clone(entry));
+        return clone(entry);
+      }
+      if (entry.revision !== expectedRevision) throw new MemoryConflictError(clone(entry));
+      if (operation && (entry.acceptanceOperations?.length ?? 0) >= 128) throw new Error("Memory acceptance operation limit reached");
+      approval(entry, authority, verification);
+      touch(entry);
+      if (operation) (entry.acceptanceOperations ??= []).push({ id: operation, expectedRevision, resultRevision: entry.revision, fingerprint });
+      return clone(entry);
+    });
+  }
+  /** Feedback changes retrieval metadata, not the content revision or approval authority. */
+  async recordFeedback(id, expectedRevision, input, authority) {
+    if (authority.kind !== "user") throw new Error("Only the user can rate reusable knowledge");
+    if (!["useful", "irrelevant", "stale", "incorrect"].includes(input.rating)) throw new Error("Unknown memory rating");
+    const note = input.note?.trim() ? text(input.note, 1e3, "feedback note") : void 0;
+    const runId = input.runId === void 0 ? void 0 : text(input.runId, 240, "feedback run ID");
+    return this.change((doc) => {
+      const entry = current(doc, id, expectedRevision, authority, true);
+      const feedback = entry.feedback ?? [];
+      const existing = feedback.find((item) => item.revision === expectedRevision && item.runId === runId);
+      if (existing?.rating === input.rating && existing.note === note) return clone(entry);
+      const next = { id: existing?.id ?? `mf-${randomUUID()}`, revision: expectedRevision, rating: input.rating, note, runId, at: Date.now(), origin: "user" };
+      entry.feedback = [...feedback.filter((item) => item.id !== next.id), next].slice(-64);
+      return clone(entry);
+    });
+  }
+  /** Promote team knowledge; branch facts need explicit branch applicability. */
+  async promote(id, expectedRevision, destination, authority, verification) {
+    return this.change((doc) => {
+      const entry = current(doc, id, expectedRevision, authority, true);
+      const candidate = validateInput({ ...entry, scope: "project", projectId: destination.projectId, applicability: destination.applicability });
+      authorize(candidate, authority, true);
+      Object.assign(entry, candidate);
+      preventPrivatePublication("project", entry.origins, authority);
+      approval(entry, authority, verification);
+      touch(entry);
+      return clone(entry);
+    });
+  }
+  /**
+   * Redact this entry. Entries that list it in `derivedFrom` keep their own bodies: that list
+   * records what was in a member's context (provenance), not text copied from it, and the
+   * origins they inherited from it stay. Source agent output in run transcripts, provider
+   * conversations and external backups is separate history; this operation does not claim to
+   * erase those records.
+   */
+  async remove(id, expectedRevision, authority) {
+    return this.change((doc) => {
+      const entry = current(doc, id, expectedRevision, authority, true);
+      redact(entry);
+      return clone(entry);
+    });
+  }
+  /** Archiving a run retires its private checkpoints and team records; project knowledge is untouched. */
+  async purgeRun(runId) {
+    return this.change((doc) => {
+      let count = 0;
+      for (const entry of doc.entries) {
+        if (entry.scope === "project" || entry.runId !== runId || entry.status === "deleted") continue;
+        redact(entry);
+        count++;
+      }
+      return count;
+    });
+  }
+  /** Offline maintenance reads provenance metadata without exporting private bodies/titles. */
+  async maintenanceEntries() {
+    const doc = await this.read();
+    return doc.entries.map(({ id, revision, scope, repo, projectId, runId, status, tags, derivedFrom, origins, sourceRefs, createdAt, updatedAt }) => clone({ id, revision, scope, repo, projectId, runId, status, tags, derivedFrom, origins, sourceRefs, createdAt, updatedAt }));
+  }
+  /** One atomic offline retirement; project guidance and live source relations stay protected. */
+  async retireMaintenance(refs) {
+    const selected = uniqueRefs(refs);
+    return this.change((doc) => {
+      const ids = new Set(selected.map((ref) => ref.id));
+      const entries = selected.map((ref) => current(doc, ref.id, ref.revision, { kind: "user" }, true));
+      if (entries.some((entry) => entry.scope === "project" || entry.tags.includes("pinned"))) throw new Error("Retention cannot erase project guidance or pinned memory");
+      if (doc.entries.some((entry) => entry.status !== "deleted" && entry.derivedFrom.some((source) => ids.has(source.id)))) throw new Error("Retention cannot erase a live memory provenance source");
+      for (const entry of entries) redact(entry);
+      return entries.length;
+    });
+  }
+  /** Inspector includes proposals, but never another member's private records. */
+  async list(query, authority) {
+    validateQuery(query, authority);
+    const doc = await this.read(query);
+    return doc.entries.filter((entry) => visible(entry, query, authority) && entry.status !== "deleted").sort((a, b) => b.updatedAt - a.updatedAt || a.id.localeCompare(b.id)).map(clone);
+  }
+  /** Bounded lexical/path selection. Revisions and exclusions can be shown in the inspector. */
+  async retrieve(query, authority) {
+    validateQuery(query, authority);
+    return this.snapshot((db) => {
+      const doc = this.database.read(db, query);
+      const eligible = doc.entries.filter((entry) => visible(entry, query, authority) && !exclusion(entry, query) && (!entry.paths.length || query.paths?.some((path) => entry.paths.some((prefix) => pathMatches(path, prefix)))));
+      const matched = this.database.search(db, query, eligible.map((entry) => entry.id));
+      const graph = this.database.graph(db, eligible);
+      const related = relatedMemories(graph, new Set(matched.keys()));
+      const selection = { entries: [], manifest: { included: [], omitted: [] } };
+      const maxEntries = bound(query.maxEntries, 8, 1, 32);
+      const maxChars = bound(query.maxChars, 8e3, 128, 32e3);
+      const words = terms(query.query ?? "");
+      const candidates = doc.entries.filter((entry) => visible(entry, query, authority) && entry.status !== "deleted").map((entry) => ({ entry, score: score(entry, query, words) + Math.min(6, matched.get(entry.id) ?? 0) + (related.has(entry.id) ? 1 : 0) })).sort((a, b) => b.score - a.score || b.entry.updatedAt - a.entry.updatedAt || a.entry.id.localeCompare(b.entry.id));
+      let size = 0;
+      for (const { entry, score: relevance } of candidates) {
+        const ref = { id: entry.id, revision: entry.revision };
+        let reason = exclusion(entry, query);
+        if (!reason && entry.paths.length && !query.paths?.some((path) => entry.paths.some((prefix) => pathMatches(path, prefix)))) reason = "outside task paths";
+        if (!reason && selection.entries.length >= maxEntries) reason = "entry budget";
+        if (!reason && size + entry.title.length + entry.body.length > maxChars) reason = "context budget";
+        if (reason) {
+          selection.manifest.omitted.push({ ...ref, reason });
+          continue;
+        }
+        selection.entries.push(clone(entry));
+        const rated = entry.feedback?.some((feedback) => feedback.revision === entry.revision && feedback.rating === "useful");
+        selection.manifest.included.push({ ...ref, reason: rated ? "applicable context with useful user feedback" : related.has(entry.id) && !matched.has(entry.id) ? "connected to matching memory through recorded evidence" : relevance > 0 ? "matching task text, tags or paths" : "applicable shared context" });
+        size += entry.title.length + entry.body.length;
+      }
+      return selection;
+    });
+  }
+  /** Resolve a recorded selection without adding newly-created or newer-revision content. */
+  async resolveSelection(query, manifest, authority) {
+    validateQuery(query, authority);
+    const doc = await this.read(query);
+    const result = { entries: [], manifest: { included: [], omitted: clone(manifest.omitted) } };
+    let size = 0;
+    for (const ref of manifest.included) {
+      const entry = doc.entries.find((candidate) => candidate.id === ref.id);
+      let reason;
+      if (!entry || entry.status === "deleted") reason = "recorded memory was deleted";
+      else if (!visible(entry, query, authority)) reason = "recorded memory is outside current scope";
+      else if (entry.revision !== ref.revision) reason = "recorded memory revision is stale";
+      else reason = exclusion(entry, query);
+      if (!reason && entry.paths.length && !query.paths?.some((path) => entry.paths.some((prefix) => pathMatches(path, prefix)))) reason = "outside task paths";
+      if (!reason && (result.entries.length >= bound(query.maxEntries, 8, 1, 32) || size + entry.title.length + entry.body.length > bound(query.maxChars, 8e3, 128, 32e3))) reason = "recorded context exceeds current budget";
+      if (reason) {
+        result.manifest.omitted.push({ id: ref.id, revision: ref.revision, reason });
+        continue;
+      }
+      result.entries.push(clone(entry));
+      result.manifest.included.push(clone(ref));
+      size += entry.title.length + entry.body.length;
+    }
+    return result;
+  }
+  /** Inspector graph uses only visible memories; proposals stay explicitly labelled by callers. */
+  async graph(query, authority) {
+    validateQuery(query, authority);
+    return this.snapshot((db) => this.database.graph(
+      db,
+      this.database.read(db, query).entries.filter((entry) => visible(entry, query, authority) && entry.status !== "deleted")
+    ));
+  }
+  async snapshot(fn) {
+    await queues.get(this.file);
+    return this.database.withDatabase((db) => {
+      db.exec("BEGIN");
+      try {
+        const result = fn(db);
+        db.exec("COMMIT");
+        return result;
+      } catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+      }
+    });
+  }
+  read(query) {
+    return this.snapshot((db) => this.database.read(db, query));
+  }
+  change(fn) {
+    const next = (queues.get(this.file) ?? Promise.resolve()).then(() => this.database.withDatabase((db) => this.database.change(db, fn)));
+    const settled = next.catch(() => void 0);
+    queues.set(this.file, settled);
+    void settled.then(() => {
+      if (queues.get(this.file) === settled) queues.delete(this.file);
+    });
+    return next;
+  }
+}
+const memoryStore = new MemoryStore();
+function redact(entry) {
+  entry.title = "";
+  entry.body = "";
+  entry.tags = [];
+  entry.paths = [];
+  entry.sourceRefs = [];
+  delete entry.verification;
+  delete entry.acceptedBy;
+  delete entry.feedback;
+  entry.status = "deleted";
+  entry.deletedAt = Date.now();
+  touch(entry);
+}
+function validateInput(raw) {
+  if (!raw || !["private", "team", "project"].includes(raw.scope)) throw new Error("Invalid memory scope");
+  if (typeof raw.repo !== "string" || !isAbsolute(raw.repo) || normalize(raw.repo) !== raw.repo) throw new Error("Memory repository must be a normalized absolute path");
+  const input = {
+    scope: raw.scope,
+    repo: raw.repo,
+    title: text(raw.title, 200, "title"),
+    body: text(raw.body, MAX_BODY, "body"),
+    tags: strings(raw.tags ?? [], 32, 80, "tags"),
+    paths: strings(raw.paths ?? [], 64, 400, "paths").map(relativePath),
+    sourceRefs: strings(raw.sourceRefs ?? [], 128, 400, "source references"),
+    derivedFrom: uniqueRefs(raw.derivedFrom ?? []),
+    applicability: validateApplicability(raw.applicability ?? { kind: "repository" })
+  };
+  for (const key of ["projectId", "runId", "memberId"]) if (raw[key] !== void 0) input[key] = text(raw[key], 240, key);
+  if (raw.operationId !== void 0) input.operationId = text(raw.operationId, 500, "operationId");
+  if (input.scope === "project" && !input.projectId) throw new Error("Project memory needs a project ID");
+  if (input.scope !== "project" && !input.runId) throw new Error("Private/team memory needs a run ID");
+  if (input.scope === "private" && !input.memberId) throw new Error("Private memory needs a member ID");
+  if (raw.expiresAt !== void 0) {
+    if (!Number.isSafeInteger(raw.expiresAt) || raw.expiresAt < 0) throw new Error("Invalid memory expiry");
+    input.expiresAt = raw.expiresAt;
+  }
+  return input;
+}
+function authorize(entry, authority, write) {
+  if (authority.repo && authority.repo !== entry.repo) throw new Error("Memory repository scope mismatch");
+  if (authority.projectId && authority.projectId !== entry.projectId) throw new Error("Memory project scope mismatch");
+  if (authority.kind === "user") {
+    if (authority.runId && authority.runId !== entry.runId) throw new Error("Memory run scope mismatch");
+    return;
+  }
+  if (authority.kind === "import") {
+    if (entry.scope !== "project") throw new Error("Historical observations must be project proposals");
+    return;
+  }
+  if (entry.projectId !== authority.projectId) throw new Error("Memory project scope mismatch");
+  if (entry.scope !== "project" && entry.runId !== authority.runId) throw new Error("Memory run scope mismatch");
+  if (entry.scope === "private" && (!authority.memberId || entry.memberId !== authority.memberId)) throw new Error("Private memory belongs to another member");
+  if (write && entry.scope === "project" && entry.runId !== authority.runId) throw new Error("A run cannot edit another run's project proposal or a user-authored rule");
+}
+function origin(authority, scope) {
+  if (authority.kind === "run") return { kind: "run", runId: authority.runId, memberId: authority.memberId, trust: authority.sourceTrust, lockedDown: authority.lockedDown, private: scope === "private" };
+  return { kind: authority.kind, trust: authority.kind === "user" ? "trusted" : "unknown", lockedDown: false, private: scope === "private" };
+}
+function sourceEntries(doc, refs, input, authority) {
+  return refs.map((ref) => {
+    const entry = doc.entries.find((candidate) => candidate.id === ref.id);
+    if (!entry) throw new Error("Memory source does not exist");
+    authorize(entry, authority, false);
+    if (entry.status !== "deleted" && entry.revision < ref.revision) throw new MemoryConflictError(clone(entry));
+    if (entry.repo !== input.repo || entry.projectId !== input.projectId) throw new Error("Derived memory cannot cross repository/project boundaries");
+    return entry;
+  });
+}
+function preventPrivatePublication(scope, origins, authority) {
+  if (scope !== "private" && authority.kind !== "user" && origins.some((source) => source.private)) throw new Error("Publishing private memory requires an explicit user action");
+}
+function approval(entry, authority, verification) {
+  if (authority.kind === "import") throw new Error("Imported observations require verification or user approval");
+  if (authority.kind === "user") {
+    entry.status = "accepted";
+    entry.acceptedBy = "user";
+    delete entry.verification;
+    return;
+  }
+  if (entry.scope === "private") {
+    entry.status = "accepted";
+    entry.acceptedBy = "owner";
+    return;
+  }
+  if (entry.scope === "team") {
+    if (!authority.canAcceptTeam) throw new Error("Only the assigned coordinator can accept team contracts");
+    entry.status = "accepted";
+    entry.acceptedBy = "team";
+    return;
+  }
+  if (authority.lockedDown || authority.sourceTrust !== "trusted" || entry.origins.some((source) => source.lockedDown || source.trust !== "trusted" || source.private)) {
+    throw new Error("Untrusted, imported or private project knowledge requires explicit user approval of this revision");
+  }
+  if (!verification?.passed || !/^[0-9a-f]{40,64}$/i.test(verification.commit) || !verification.evidenceRefs?.length || verification.evidenceRefs.some((ref) => typeof ref !== "string" || !ref.trim())) {
+    throw new Error("Project promotion requires passing runtime verification with commit and evidence references");
+  }
+  if (entry.applicability.kind === "repository" && !verification.merged) throw new Error("Unmerged knowledge must stay team-scoped or explicitly branch-specific");
+  if (entry.applicability.kind === "branch") {
+    if (!entry.applicability.commit || entry.applicability.branch !== verification.branch || entry.applicability.commit !== verification.commit) throw new Error("Branch knowledge must match the verified branch and commit");
+  }
+  entry.status = "accepted";
+  entry.acceptedBy = "verification";
+  entry.verification = clone(verification);
+}
+function validateQuery(query, authority) {
+  if (!query || typeof query.repo !== "string" || !isAbsolute(query.repo) || normalize(query.repo) !== query.repo) throw new Error("Memory query needs an absolute repository");
+  if (authority.repo && authority.repo !== query.repo) throw new Error("Memory repository scope mismatch");
+  if (authority.projectId && authority.projectId !== query.projectId) throw new Error("Memory project scope mismatch");
+  if (authority.kind === "run") {
+    if (query.projectId !== authority.projectId || query.runId && query.runId !== authority.runId || query.memberId && query.memberId !== authority.memberId) throw new Error("Memory query scope mismatch");
+  }
+  if (query.paths) strings(query.paths, 64, 400, "paths").forEach(relativePath);
+}
+function visible(entry, query, authority) {
+  if (entry.repo !== query.repo || entry.projectId !== query.projectId || query.scope && entry.scope !== query.scope) return false;
+  if (entry.scope === "private" && (entry.runId !== query.runId || entry.memberId !== query.memberId)) return false;
+  if (entry.scope === "team" && entry.runId !== query.runId) return false;
+  try {
+    authorize(entry, authority, false);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function exclusion(entry, query) {
+  if (entry.status !== "accepted") return "unaccepted proposal";
+  const feedback = entry.feedback?.filter((item) => item.revision === entry.revision) ?? [];
+  if (feedback.some((item) => item.rating === "stale" || item.rating === "incorrect")) return "user marked this revision stale or incorrect";
+  if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) return "expired";
+  if (entry.applicability.kind === "branch") {
+    if (entry.applicability.branch !== query.branch) return "different branch";
+    const commit = entry.applicability.commit;
+    if (commit && commit !== query.commit && !query.allowedCommits?.includes(commit)) return "unverified commit applicability";
+  }
+  return void 0;
+}
+function score(entry, query, words) {
+  const available = terms(`${entry.title} ${entry.body} ${entry.tags.join(" ")}`);
+  let value = 0;
+  for (const word of words) if (available.has(word)) value++;
+  for (const tag of query.tags ?? []) if (entry.tags.includes(tag)) value += 3;
+  for (const path of query.paths ?? []) if (entry.paths.some((prefix) => pathMatches(path, prefix))) value += 5;
+  const feedback = entry.feedback?.filter((item) => item.revision === entry.revision) ?? [];
+  value += Math.max(-3, Math.min(3, feedback.reduce((sum, item) => sum + (item.rating === "useful" ? 1 : item.rating === "irrelevant" ? -1 : 0), 0)));
+  return value;
+}
+function pathMatches(path, prefix) {
+  return path === "*" || prefix === "*" || path === prefix || path.startsWith(prefix + "/") || prefix.startsWith(path + "/");
+}
+function terms(value) {
+  return new Set(value.toLowerCase().match(/[a-z0-9_]{3,}/g) ?? []);
+}
+function clone(value) {
+  return structuredClone(value);
+}
+function touch(entry) {
+  entry.revision++;
+  entry.updatedAt = Date.now();
+}
+function bound(value, fallback, min, max) {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(min, Math.min(max, Math.floor(value))) : fallback;
+}
+function text(value, max, name) {
+  if (typeof value !== "string" || !value.trim() || value.length > max || value.includes("\0")) throw new Error(`Invalid memory ${name} (1\u2013${max} characters)`);
+  return value.trim();
+}
+function strings(value, max, length, name) {
+  if (!Array.isArray(value) || value.length > max) throw new Error(`Invalid memory ${name}`);
+  return [...new Set(value.map((item) => text(item, length, name)))];
+}
+function relativePath(value) {
+  const path = value.replace(/\\/g, "/").replace(/\/$/, "");
+  if (!path || path.startsWith("/") || /^[a-z]:/i.test(path) || path.split("/").some((part) => !part || part === "." || part === "..")) throw new Error("Memory paths must stay inside the repository");
+  return path;
+}
+function validateApplicability(value) {
+  if (value?.kind === "repository") return { kind: "repository" };
+  if (value?.kind !== "branch") throw new Error("Invalid memory applicability");
+  const branch = text(value.branch, 240, "branch");
+  if (value.commit !== void 0 && !/^[0-9a-f]{40,64}$/i.test(value.commit)) throw new Error("Memory applicability needs a full commit SHA");
+  return { kind: "branch", branch, ...value.commit ? { commit: value.commit } : {} };
+}
+function uniqueRefs(value) {
+  if (!Array.isArray(value) || value.length > 1024) throw new Error("Too many memory derivation references");
+  const refs = /* @__PURE__ */ new Map();
+  for (const ref of value) {
+    if (!ref || !Number.isSafeInteger(ref.revision) || ref.revision < 1) throw new Error("Invalid memory revision reference");
+    const id = text(ref.id, 240, "reference");
+    refs.set(`${id}@${ref.revision}`, { id, revision: ref.revision });
+  }
+  return [...refs.values()].sort((a, b) => a.id.localeCompare(b.id) || a.revision - b.revision);
+}
+function unionOrigins(origins) {
+  return [...new Map(origins.map((source) => [JSON.stringify(source), source])).entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, source]) => source);
+}
+function current(doc, id, revision, authority, write = false) {
+  const entry = doc.entries.find((candidate) => candidate.id === id);
+  if (!entry || entry.status === "deleted") throw new Error("Memory entry not found");
+  authorize(entry, authority, write);
+  if (entry.revision !== revision) throw new MemoryConflictError(clone(entry));
+  return entry;
+}
+function hashOperation(input, authority) {
+  return createHash("sha256").update(JSON.stringify({ input, origin: origin(authority, input.scope) })).digest("hex");
+}
+function canonicalJson(value) {
+  const sorted = (item) => Array.isArray(item) ? item.map(sorted) : item && typeof item === "object" ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)).map(([key, value2]) => [key, sorted(value2)])) : item;
+  return JSON.stringify(sorted(value));
+}
+function validateDocument(raw) {
+  try {
+    if (Buffer.byteLength(raw) > MAX_FILE) throw new Error("file is too large");
+    const document = JSON.parse(raw);
+    if (!document || typeof document !== "object") throw new Error("invalid document");
+    const doc = document;
+    if (doc.schemaVersion !== 1 || !Array.isArray(doc.entries) || doc.entries.filter((entry) => entry?.status !== "deleted" && entry?.scope === "project").length > MAX_ENTRIES) throw new Error("unsupported schema");
+    const ids = /* @__PURE__ */ new Set();
+    for (const entry of doc.entries) {
+      if (!entry || typeof entry !== "object" || typeof entry.id !== "string" || ids.has(entry.id) || !Number.isSafeInteger(entry.revision) || entry.revision < 1 || !["proposed", "accepted", "deleted"].includes(entry.status)) throw new Error("invalid entry");
+      ids.add(entry.id);
+      validateInput(entry.status === "deleted" ? { ...entry, title: "deleted", body: "deleted" } : entry);
+      if (!Array.isArray(entry.origins) || !entry.origins.length || entry.origins.some((source) => !source || !["user", "run", "import"].includes(source.kind) || !["trusted", "untrusted", "unknown"].includes(source.trust) || typeof source.lockedDown !== "boolean" || typeof source.private !== "boolean")) throw new Error("invalid provenance");
+      if (!Array.isArray(entry.paths) || !Array.isArray(entry.tags) || !Array.isArray(entry.derivedFrom) || !Array.isArray(entry.sourceRefs) || !Number.isFinite(entry.createdAt) || !Number.isFinite(entry.updatedAt)) throw new Error("incomplete entry");
+      if (entry.acceptanceOperations !== void 0 && (!Array.isArray(entry.acceptanceOperations) || entry.acceptanceOperations.length > 128 || entry.acceptanceOperations.some((operation) => !operation || typeof operation.id !== "string" || !operation.id || operation.id.length > 500 || !Number.isSafeInteger(operation.expectedRevision) || operation.expectedRevision < 1 || operation.resultRevision !== operation.expectedRevision + 1 || typeof operation.fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(operation.fingerprint)))) throw new Error("invalid acceptance operation");
+    }
+    return doc;
+  } catch (error) {
+    throw new Error(`Memory store cannot be read; no records were changed: ${error.message}`);
+  }
+}
+function relatedMemories(graph, matches) {
+  const nodes = new Map(graph.entities.map((entity) => [entity.id, entity]));
+  let frontier = new Set(graph.entities.filter((entity) => entity.kind === "memory" && matches.has(entity.key)).map((entity) => entity.id));
+  const visited = new Set(frontier);
+  for (let hop = 0; hop < 2; hop++) {
+    const next = /* @__PURE__ */ new Set();
+    for (const edge of graph.relationships) {
+      if (frontier.has(edge.from) && !visited.has(edge.to)) next.add(edge.to);
+      if (frontier.has(edge.to) && !visited.has(edge.from)) next.add(edge.from);
+    }
+    for (const id of next) visited.add(id);
+    frontier = next;
+  }
+  return new Set([...visited].flatMap((id) => nodes.get(id)?.kind === "memory" ? [nodes.get(id).key] : []));
+}
+export {
+  MemoryConflictError,
+  MemoryStore,
+  memoryStore,
+  validateDocument
+};

package/src/merge-validation.js

@@ -0,0 +1,58 @@
+import { assertWorktree, git, resolveCommit } from "./git.js";
+import { inTemporaryWorktree } from "./readiness.js";
+import { runCheck } from "./checks.js";
+import { runVerification } from "./verification.js";
+import { readOnlyGitMetadata } from "./agent-container.js";
+async function validateMergeTarget(repo, input) {
+  const [source, target] = await Promise.all([resolveCommit(repo, `refs/heads/${input.branch}`), resolveCommit(repo, `refs/heads/${input.into}`)]);
+  return inTemporaryWorktree(repo, target, async (path) => {
+    const checkout = await assertWorktree(repo, { path });
+    const container = input.container ? { ...input.container, readOnly: [.../* @__PURE__ */ new Set([...input.container.readOnly ?? [], ...readOnlyGitMetadata(path)])] } : void 0;
+    const merged = await git(["-c", "core.hooksPath=/dev/null", "-c", "user.name=code-flow validation", "-c", "user.email=validation@code-flow.invalid", "merge", "--no-commit", "--no-ff", source], checkout, { signal: input.signal });
+    const result = { branch: input.branch, into: input.into, source, target, conflicts: [], at: Date.now() };
+    if (merged.code) {
+      result.conflicts = (await git(["diff", "--name-only", "--diff-filter=U", "-z"], checkout)).stdout.split("\0").filter(Boolean);
+      if (!result.conflicts.length) throw new Error(merged.stderr.trim() || merged.stdout.trim() || "Cannot construct the merge target");
+      return result;
+    }
+    const tree = await git(["write-tree"], checkout);
+    if (tree.code) throw new Error(tree.stderr.trim() || "Cannot record the merge tree");
+    result.tree = tree.stdout.trim();
+    const assertCandidate = async (stage) => {
+      if (input.signal?.aborted) throw new Error("Merge validation was cancelled");
+      await assertWorktree(repo, { path });
+      const options = { signal: input.signal, timeoutMs: 1e4 };
+      const [currentHead, currentTree, unstaged, flags] = await Promise.all([
+        git(["rev-parse", "--verify", "HEAD^{commit}"], checkout, options),
+        git(["write-tree"], checkout, options),
+        git(["diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--quiet", "--exit-code", "--"], checkout, options),
+        git(["ls-files", "-v", "-z"], checkout, options)
+      ]);
+      if (input.signal?.aborted) throw new Error("Merge validation was cancelled");
+      const hidden = flags.stdout.split("\0").some((file) => /^[a-zS] /.test(file));
+      if (currentHead.code || currentTree.code || unstaged.code || flags.code || hidden || currentHead.stdout.trim() !== target || currentTree.stdout.trim() !== result.tree) throw new Error(`Merge validation ${stage} changed tracked files, the staged tree or the checkout commit, or hid tracked files from comparison. The original merge candidate was not verified.`);
+    };
+    await assertCandidate("merge construction");
+    if (input.setup) {
+      await assertCandidate("before setup");
+      const setup = await runCheck(path, input.setup, { signal: input.signal, container, timeoutMs: 12e4 });
+      await assertCandidate("setup");
+      if (!setup.ok) throw new Error(`Merge validation setup failed: ${setup.output.slice(-2e3)}`);
+    }
+    result.report = await runVerification(path, input.profile, {
+      signal: input.signal,
+      container,
+      execute: async (check, options) => {
+        await assertCandidate(`before gate ${check.id}`);
+        const checked = await runCheck(path, check.command, options);
+        await assertCandidate(`gate ${check.id}`);
+        return checked;
+      }
+    });
+    await assertCandidate("completion");
+    return result;
+  }, input.signal);
+}
+export {
+  validateMergeTarget
+};