@etiquekit/etq 1.0.14 → 1.0.15

package/packages/control/src/memory/store-lifecycle.ts

@@ -1,509 +0,0 @@
-import { createHash } from 'node:crypto';
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join, posix, resolve, sep } from 'node:path';
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import {
-  WORKSPACE_MEMORY_ACCESS,
-  WORKSPACE_MEMORY_MOUNT_MODES,
-  WORKSPACE_MEMORY_SCOPES,
-  WORKSPACE_MEMORY_WRITE_POLICIES,
-  type WorkspaceMemoryAccess,
-  type WorkspaceMemoryMountMode,
-  type WorkspaceMemoryScope,
-  type WorkspaceMemoryStore,
-  type WorkspaceMemoryWritePolicy,
-} from '../workspace/authority';
-import { assertSharedMemoryScopeId, assertSharedMemoryText, detectMemoryRiskFlags } from './sanitize';
-import { EVIDENCE_REF_TYPES, type EvidenceRef, type EvidenceRefType } from './types';
-
-type JsonRecord = Record<string, unknown>;
-
-export interface MemoryStoreManifest extends WorkspaceMemoryStore {
-  schema: 'memory-store.v0';
-  created_at: string;
-  storage_layout: {
-    manifest_ref: 'store.yaml';
-    candidate_files_dir: 'candidates/files';
-    candidate_entries_dir: 'candidates/entries';
-    rollups_dir: 'rollups';
-  };
-  authority_boundary: {
-    store_can_authorize_work: false;
-    agent_can_write_canonical_memory: false;
-    shared_write_back_requires_promotion: true;
-  };
-}
-
-export interface MemoryStoreEntry {
-  schema: 'memory-store-entry.v0';
-  entry_id: string;
-  store_id: string;
-  path: string;
-  status: 'candidate';
-  created_at: string;
-  content_ref: string;
-  evidence_refs: EvidenceRef[];
-  risk_flags: string[];
-  authority_boundary: {
-    entry_can_authorize_work: false;
-    entry_can_replace_canonical_memory: false;
-    agent_wrote_canonical_memory: false;
-  };
-}
-
-export interface MemoryConsolidationRollup {
-  schema: 'memory-consolidation-rollup.v0';
-  rollup_id: string;
-  created_at: string;
-  input_stores: string[];
-  output_store: string;
-  candidate_count: number;
-  entry_refs: string[];
-  summary: string;
-  output_policy: 'candidate_only' | 'curator_promoted';
-  status: 'candidate';
-  authority_boundary: {
-    rollup_can_authorize_work: false;
-    mutates_input_store: false;
-    promotes_without_curator: false;
-  };
-}
-
-export interface MemoryStoreSummary {
-  store: MemoryStoreManifest;
-  counts: {
-    candidate_entries: number;
-    rollups: number;
-  };
-}
-
-const LAYOUT = {
-  manifest_ref: 'store.yaml',
-  candidate_files_dir: 'candidates/files',
-  candidate_entries_dir: 'candidates/entries',
-  rollups_dir: 'rollups',
-} as const;
-
-export function defaultMemoryStoresRoot(projectRoot: string): string {
-  return join(projectRoot, '.etiquette', 'memory', 'stores');
-}
-
-function isoNow(at?: string): string {
-  const value = at ?? new Date().toISOString();
-  if (!Number.isFinite(Date.parse(value))) throw new Error('--at must be an ISO-8601 timestamp');
-  return new Date(value).toISOString();
-}
-
-function stableHash(value: unknown): string {
-  return createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 16);
-}
-
-function asRecord(value: unknown, name: string): JsonRecord {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-    throw new Error(`${name} must be an object`);
-  }
-  return value as JsonRecord;
-}
-
-function asString(record: JsonRecord, key: string): string {
-  const value = record[key];
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`${key} must be a non-empty string`);
-  }
-  return value.trim();
-}
-
-function asBoolean(record: JsonRecord, key: string): boolean {
-  const value = record[key];
-  if (typeof value !== 'boolean') throw new Error(`${key} must be a boolean`);
-  return value;
-}
-
-function asEnum<T extends readonly string[]>(values: T, raw: unknown, key: string): T[number] {
-  if (typeof raw !== 'string' || !(values as readonly string[]).includes(raw)) {
-    throw new Error(`${key} must be one of: ${values.join(', ')}`);
-  }
-  return raw as T[number];
-}
-
-function storeDir(root: string, storeId: string): string {
-  return join(root, storeId);
-}
-
-function assertStoreId(storeId: string): string {
-  assertSharedMemoryScopeId(storeId, 'store_id');
-  return storeId;
-}
-
-function assertMemoryPath(raw: string): string {
-  const value = raw.trim();
-  if (!value) throw new Error('--path is required');
-  if (value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value)) {
-    throw new Error('--path must be repo-relative, not an absolute local path');
-  }
-  if (value.includes('\\')) throw new Error('--path must use POSIX / separators');
-  const normalized = posix.normalize(value);
-  if (normalized === '.' || normalized.startsWith('../') || normalized === '..') {
-    throw new Error('--path must stay inside the memory store');
-  }
-  assertSharedMemoryText(normalized, 'path');
-  return normalized;
-}
-
-function assertStoreRelativeRef(raw: string, field: string): string {
-  const value = raw.trim();
-  if (!value) throw new Error(`${field} is required`);
-  if (value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value)) {
-    throw new Error(`${field} must be store-relative, not an absolute local path`);
-  }
-  if (value.includes('\\')) throw new Error(`${field} must use POSIX / separators`);
-  const normalized = posix.normalize(value);
-  if (normalized === '.' || normalized.startsWith('../') || normalized === '..') {
-    throw new Error(`${field} must stay inside the memory store`);
-  }
-  assertSharedMemoryText(normalized, field);
-  return normalized.replace(/^\.\/+/, '');
-}
-
-function relativeRef(...parts: string[]): string {
-  return parts.join('/').replaceAll(sep, '/');
-}
-
-async function readStructured(path: string): Promise<unknown> {
-  const raw = await readFile(path, 'utf-8');
-  return parseYaml(raw) as unknown;
-}
-
-async function writeYaml(path: string, value: unknown): Promise<void> {
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, stringifyYaml(value));
-}
-
-function validateStoreShape(store: WorkspaceMemoryStore, prefix = 'memory store'): void {
-  assertStoreId(store.store_id);
-  if (store.access === 'read_only' && store.write_policy !== 'none') {
-    throw new Error(`${prefix} read_only stores must use write_policy: none`);
-  }
-  if (store.access === 'read_write' && store.write_policy === 'none') {
-    throw new Error(`${prefix} read_write stores require candidate_only or curator_promoted write_policy`);
-  }
-  if (store.scope === 'org' && store.access === 'read_write' && store.write_policy !== 'curator_promoted') {
-    throw new Error(`${prefix} org shared read_write stores require write_policy: curator_promoted`);
-  }
-  if (store.scope === 'workspace' && store.access === 'read_write' && store.write_policy === 'candidate_only') {
-    throw new Error(`${prefix} workspace shared read_write stores require curator_promoted writes`);
-  }
-  if (store.access === 'read_write' && store.evidence_required !== true) {
-    throw new Error(`${prefix} read_write stores must require evidence`);
-  }
-}
-
-function parseMemoryStoreManifest(value: unknown): MemoryStoreManifest {
-  const record = asRecord(value, 'memory_store');
-  if (asEnum(['memory-store.v0'] as const, record.schema, 'schema') !== 'memory-store.v0') {
-    throw new Error('schema must be memory-store.v0');
-  }
-  const store: MemoryStoreManifest = {
-    schema: 'memory-store.v0',
-    store_id: asString(record, 'store_id'),
-    scope: asEnum(WORKSPACE_MEMORY_SCOPES, record.scope, 'scope') as WorkspaceMemoryScope,
-    access: asEnum(WORKSPACE_MEMORY_ACCESS, record.access, 'access') as WorkspaceMemoryAccess,
-    mount_mode: asEnum(WORKSPACE_MEMORY_MOUNT_MODES, record.mount_mode, 'mount_mode') as WorkspaceMemoryMountMode,
-    write_policy: asEnum(WORKSPACE_MEMORY_WRITE_POLICIES, record.write_policy, 'write_policy') as WorkspaceMemoryWritePolicy,
-    evidence_required: asBoolean(record, 'evidence_required'),
-    created_at: asString(record, 'created_at'),
-    storage_layout: LAYOUT,
-    authority_boundary: {
-      store_can_authorize_work: false,
-      agent_can_write_canonical_memory: false,
-      shared_write_back_requires_promotion: true,
-    },
-  };
-  validateStoreShape(store);
-  return store;
-}
-
-function parseMemoryStoreEntry(value: unknown): MemoryStoreEntry {
-  const record = asRecord(value, 'memory_store_entry');
-  if (asEnum(['memory-store-entry.v0'] as const, record.schema, 'schema') !== 'memory-store-entry.v0') {
-    throw new Error('schema must be memory-store-entry.v0');
-  }
-  const refs = record.evidence_refs;
-  if (!Array.isArray(refs)) throw new Error('evidence_refs must be an array');
-  return {
-    schema: 'memory-store-entry.v0',
-    entry_id: asString(record, 'entry_id'),
-    store_id: asString(record, 'store_id'),
-    path: asString(record, 'path'),
-    status: 'candidate',
-    created_at: asString(record, 'created_at'),
-    content_ref: asString(record, 'content_ref'),
-    evidence_refs: refs.map((item, index) => {
-      const ref = asRecord(item, `evidence_refs[${index}]`);
-      return {
-        type: asEnum(EVIDENCE_REF_TYPES, ref.type, `evidence_refs[${index}].type`) as EvidenceRefType,
-        ref: asString(ref, 'ref'),
-      };
-    }),
-    risk_flags: Array.isArray(record.risk_flags) ? record.risk_flags.map(String) : [],
-    authority_boundary: {
-      entry_can_authorize_work: false,
-      entry_can_replace_canonical_memory: false,
-      agent_wrote_canonical_memory: false,
-    },
-  };
-}
-
-export function parseEvidenceRefs(raw: string): EvidenceRef[] {
-  const refs = raw.split(',').map((item) => item.trim()).filter(Boolean).map((item) => {
-    const colon = item.indexOf(':');
-    if (colon <= 0 || colon === item.length - 1) {
-      throw new Error('--evidence entries must use type:ref, for example receipt:abc');
-    }
-    const type = item.slice(0, colon);
-    const ref = item.slice(colon + 1);
-    if (!(EVIDENCE_REF_TYPES as readonly string[]).includes(type)) {
-      throw new Error(`--evidence type must be one of: ${EVIDENCE_REF_TYPES.join(', ')}`);
-    }
-    assertSharedMemoryText(ref, 'evidence.ref');
-    return { type: type as EvidenceRefType, ref };
-  });
-  if (refs.length === 0) throw new Error('--evidence must include at least one type:ref');
-  return refs;
-}
-
-export async function initMemoryStore(options: {
-  projectRoot: string;
-  storesRoot?: string;
-  storeId: string;
-  scope: WorkspaceMemoryScope;
-  access: WorkspaceMemoryAccess;
-  mountMode?: WorkspaceMemoryMountMode;
-  writePolicy?: WorkspaceMemoryWritePolicy;
-  evidenceRequired?: boolean;
-  at?: string;
-}): Promise<MemoryStoreManifest> {
-  const manifest: MemoryStoreManifest = {
-    schema: 'memory-store.v0',
-    store_id: assertStoreId(options.storeId),
-    scope: options.scope,
-    access: options.access,
-    mount_mode: options.mountMode ?? 'filesystem_like',
-    write_policy: options.writePolicy ?? (options.access === 'read_only' ? 'none' : 'candidate_only'),
-    evidence_required: options.evidenceRequired ?? options.access === 'read_write',
-    created_at: isoNow(options.at),
-    storage_layout: LAYOUT,
-    authority_boundary: {
-      store_can_authorize_work: false,
-      agent_can_write_canonical_memory: false,
-      shared_write_back_requires_promotion: true,
-    },
-  };
-  validateStoreShape(manifest);
-  const root = resolve(options.storesRoot ?? defaultMemoryStoresRoot(options.projectRoot));
-  const dir = storeDir(root, manifest.store_id);
-  await mkdir(join(dir, LAYOUT.candidate_files_dir), { recursive: true });
-  await mkdir(join(dir, LAYOUT.candidate_entries_dir), { recursive: true });
-  await mkdir(join(dir, LAYOUT.rollups_dir), { recursive: true });
-  await writeYaml(join(dir, LAYOUT.manifest_ref), manifest);
-  return manifest;
-}
-
-export async function loadMemoryStoreManifest(options: {
-  projectRoot: string;
-  storesRoot?: string;
-  storeId: string;
-}): Promise<MemoryStoreManifest> {
-  const root = resolve(options.storesRoot ?? defaultMemoryStoresRoot(options.projectRoot));
-  return parseMemoryStoreManifest(await readStructured(join(storeDir(root, assertStoreId(options.storeId)), LAYOUT.manifest_ref)));
-}
-
-async function countYamlFiles(dir: string): Promise<number> {
-  try {
-    const items = await readdir(dir, { withFileTypes: true });
-    return items.filter((item) => item.isFile() && /\.ya?ml$/i.test(item.name)).length;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 0;
-    throw error;
-  }
-}
-
-async function summarizeStore(projectRoot: string, storesRoot: string | undefined, store: MemoryStoreManifest): Promise<MemoryStoreSummary> {
-  const root = resolve(storesRoot ?? defaultMemoryStoresRoot(projectRoot));
-  const dir = storeDir(root, store.store_id);
-  return {
-    store,
-    counts: {
-      candidate_entries: await countYamlFiles(join(dir, LAYOUT.candidate_entries_dir)),
-      rollups: await countYamlFiles(join(dir, LAYOUT.rollups_dir)),
-    },
-  };
-}
-
-export async function showMemoryStore(options: {
-  projectRoot: string;
-  storesRoot?: string;
-  storeId: string;
-}): Promise<MemoryStoreSummary> {
-  const store = await loadMemoryStoreManifest(options);
-  return summarizeStore(options.projectRoot, options.storesRoot, store);
-}
-
-export async function listMemoryStores(options: {
-  projectRoot: string;
-  storesRoot?: string;
-}): Promise<MemoryStoreSummary[]> {
-  const root = resolve(options.storesRoot ?? defaultMemoryStoresRoot(options.projectRoot));
-  let items;
-  try {
-    items = await readdir(root, { withFileTypes: true });
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
-    throw error;
-  }
-  const summaries: MemoryStoreSummary[] = [];
-  for (const item of items) {
-    if (!item.isDirectory()) continue;
-    const store = await loadMemoryStoreManifest({ ...options, storeId: item.name });
-    summaries.push(await summarizeStore(options.projectRoot, options.storesRoot, store));
-  }
-  return summaries.sort((a, b) => a.store.store_id.localeCompare(b.store.store_id));
-}
-
-export async function addMemoryStoreCandidate(options: {
-  projectRoot: string;
-  storesRoot?: string;
-  storeId: string;
-  path: string;
-  content: string;
-  evidenceRefs: EvidenceRef[];
-  at?: string;
-}): Promise<MemoryStoreEntry> {
-  const store = await loadMemoryStoreManifest(options);
-  if (store.access === 'read_only' || store.write_policy === 'none') {
-    throw new Error(`memory store ${store.store_id} is read-only and cannot accept candidates`);
-  }
-  if (store.evidence_required && options.evidenceRefs.length === 0) {
-    throw new Error(`memory store ${store.store_id} requires evidence refs`);
-  }
-  const path = assertMemoryPath(options.path);
-  assertSharedMemoryText(options.content, 'content');
-  const createdAt = isoNow(options.at);
-  const entryId = `mem-entry:${stableHash({
-    store_id: store.store_id,
-    path,
-    content: options.content,
-    evidence_refs: options.evidenceRefs,
-  })}`;
-  const root = resolve(options.storesRoot ?? defaultMemoryStoresRoot(options.projectRoot));
-  const dir = storeDir(root, store.store_id);
-  const contentRef = relativeRef(LAYOUT.candidate_files_dir, path);
-  const entry: MemoryStoreEntry = {
-    schema: 'memory-store-entry.v0',
-    entry_id: entryId,
-    store_id: store.store_id,
-    path,
-    status: 'candidate',
-    created_at: createdAt,
-    content_ref: contentRef,
-    evidence_refs: options.evidenceRefs,
-    risk_flags: detectMemoryRiskFlags(options.content),
-    authority_boundary: {
-      entry_can_authorize_work: false,
-      entry_can_replace_canonical_memory: false,
-      agent_wrote_canonical_memory: false,
-    },
-  };
-  await mkdir(dirname(join(dir, contentRef)), { recursive: true });
-  await writeFile(join(dir, contentRef), options.content);
-  await writeYaml(join(dir, LAYOUT.candidate_entries_dir, `${entryId.replace(':', '-')}.yaml`), entry);
-  return entry;
-}
-
-async function loadCandidateEntries(projectRoot: string, storesRoot: string | undefined, storeId: string): Promise<MemoryStoreEntry[]> {
-  const root = resolve(storesRoot ?? defaultMemoryStoresRoot(projectRoot));
-  const dir = join(storeDir(root, assertStoreId(storeId)), LAYOUT.candidate_entries_dir);
-  let items;
-  try {
-    items = await readdir(dir, { withFileTypes: true });
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
-    throw error;
-  }
-  const entries: MemoryStoreEntry[] = [];
-  for (const item of items) {
-    if (!item.isFile() || !/\.ya?ml$/i.test(item.name)) continue;
-    entries.push(parseMemoryStoreEntry(await readStructured(join(dir, item.name))));
-  }
-  return entries.sort((a, b) => a.entry_id.localeCompare(b.entry_id));
-}
-
-export async function listMemoryStoreCandidateEntries(options: {
-  projectRoot: string;
-  storesRoot?: string;
-  storeId: string;
-}): Promise<MemoryStoreEntry[]> {
-  return loadCandidateEntries(options.projectRoot, options.storesRoot, options.storeId);
-}
-
-export async function readMemoryStoreCandidateContent(options: {
-  projectRoot: string;
-  storesRoot?: string;
-  storeId: string;
-  entry: MemoryStoreEntry;
-}): Promise<string> {
-  if (options.entry.store_id !== options.storeId) {
-    throw new Error(`entry ${options.entry.entry_id} belongs to store ${options.entry.store_id}, not ${options.storeId}`);
-  }
-  const root = resolve(options.storesRoot ?? defaultMemoryStoresRoot(options.projectRoot));
-  const contentRef = assertStoreRelativeRef(options.entry.content_ref, 'content_ref');
-  return readFile(join(storeDir(root, assertStoreId(options.storeId)), contentRef), 'utf-8');
-}
-
-export async function consolidateMemoryStores(options: {
-  projectRoot: string;
-  storesRoot?: string;
-  inputStores: string[];
-  outputStore: string;
-  at?: string;
-}): Promise<MemoryConsolidationRollup> {
-  if (options.inputStores.length === 0) throw new Error('--input must include at least one store id');
-  const output = await loadMemoryStoreManifest({ ...options, storeId: options.outputStore });
-  if (output.access !== 'read_write' || output.write_policy === 'none') {
-    throw new Error(`consolidation output store ${output.store_id} must be read_write`);
-  }
-  const entries = (await Promise.all(options.inputStores.map((storeId) => loadCandidateEntries(
-    options.projectRoot,
-    options.storesRoot,
-    storeId,
-  )))).flat();
-  const createdAt = isoNow(options.at);
-  const rollupId = `mem-rollup:${stableHash({
-    input_stores: options.inputStores,
-    output_store: output.store_id,
-    entries: entries.map((entry) => entry.entry_id),
-    at: createdAt,
-  })}`;
-  const rollup: MemoryConsolidationRollup = {
-    schema: 'memory-consolidation-rollup.v0',
-    rollup_id: rollupId,
-    created_at: createdAt,
-    input_stores: options.inputStores.map(assertStoreId),
-    output_store: output.store_id,
-    candidate_count: entries.length,
-    entry_refs: entries.map((entry) => `${entry.store_id}:${entry.entry_id}`),
-    summary: entries.length === 0
-      ? 'No candidate memory entries were available for consolidation.'
-      : `Consolidated ${entries.length} candidate memory entr${entries.length === 1 ? 'y' : 'ies'} from ${options.inputStores.join(', ')}.`,
-    output_policy: output.write_policy,
-    status: 'candidate',
-    authority_boundary: {
-      rollup_can_authorize_work: false,
-      mutates_input_store: false,
-      promotes_without_curator: false,
-    },
-  };
-  const root = resolve(options.storesRoot ?? defaultMemoryStoresRoot(options.projectRoot));
-  await writeYaml(join(storeDir(root, output.store_id), LAYOUT.rollups_dir, `${rollupId.replace(':', '-')}.yaml`), rollup);
-  return rollup;
-}