vgxness 0.1.0

package/dist/memory/import/dry-run-planner.js

@@ -0,0 +1,58 @@
+import { validateMemoryImportPackage } from './package.js';
+export function planMemoryImportDryRun(input) {
+    const validation = validateMemoryImportPackage(input.packageJson);
+    if (!validation.ok)
+        return validationFailure(`Invalid memory import package: ${formatValidationErrors(validation.errors)}`);
+    const packageValue = validation.package;
+    return {
+        ok: true,
+        value: {
+            mode: 'dry-run',
+            migrationBatchId: packageValue.migrationBatchId,
+            source: packageValue.source,
+            target: {
+                databasePath: input.targetDatabase.path,
+                databasePathSource: input.targetDatabase.source,
+            },
+            counts: {
+                observations: packageValue.observations.length,
+                sddArtifacts: packageValue.sddArtifacts?.length ?? 0,
+                sessionSummaries: packageValue.sessionSummaries?.length ?? 0,
+            },
+            plannedCreates: {
+                observations: packageValue.observations.map((observation) => ({
+                    project: observation.project,
+                    scope: observation.scope,
+                    type: observation.type,
+                    title: observation.title,
+                    ...(observation.topicKey !== undefined ? { topicKey: observation.topicKey } : {}),
+                })),
+                sddArtifacts: (packageValue.sddArtifacts ?? []).map((artifact) => ({
+                    project: artifact.project,
+                    change: artifact.change,
+                    phase: artifact.phase,
+                    ...(artifact.topicKey !== undefined ? { topicKey: artifact.topicKey } : {}),
+                })),
+                sessionSummaries: (packageValue.sessionSummaries ?? []).map((summary) => ({
+                    ...(summary.project !== undefined ? { project: summary.project } : {}),
+                    ...(summary.sourceSessionId !== undefined ? { sourceSessionId: summary.sourceSessionId } : {}),
+                    ...(summary.sessionId !== undefined ? { sessionId: summary.sessionId } : {}),
+                    ...(summary.topicKey !== undefined ? { topicKey: summary.topicKey } : {}),
+                })),
+            },
+            safety: {
+                mutatesDatabase: false,
+                writesObservations: false,
+                writesSddArtifacts: false,
+                writesSessionSummaries: false,
+                writesTraces: false,
+            },
+        },
+    };
+}
+function formatValidationErrors(errors) {
+    return errors.map((error) => `${error.path}: ${error.message}`).join('; ');
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}

package/dist/memory/import/index.js

@@ -0,0 +1,3 @@
+export * from './package.js';
+export * from './dry-run-planner.js';
+export * from './observation-writer.js';

package/dist/memory/import/observation-writer.js

@@ -0,0 +1,220 @@
+import { SddWorkflowService } from '../../sdd/sdd-workflow-service.js';
+import { sddTopicKey } from '../../sdd/schema.js';
+import { validateMemoryImportPackage } from './package.js';
+const context = { actor: 'memory-import' };
+export function writeMemoryImportObservations(input) {
+    const validation = validateMemoryImportPackage(input.packageJson);
+    if (!validation.ok)
+        return validationFailure(`Invalid memory import package: ${formatValidationErrors(validation.errors)}`);
+    const packageValue = validation.package;
+    const summary = {
+        mode: 'write',
+        duplicatePolicy: input.duplicatePolicy,
+        migrationBatchId: packageValue.migrationBatchId,
+        source: packageValue.source,
+        target: {
+            databasePath: input.targetDatabase.path,
+            databasePathSource: input.targetDatabase.source,
+        },
+        counts: {
+            observations: emptyCounts(),
+            sddArtifacts: emptyCounts(),
+            sessionSummaries: emptyCounts(),
+        },
+        observations: { created: [], skipped: [], overwritten: [], failed: [] },
+        sddArtifacts: { created: [], skipped: [], overwritten: [], failed: [] },
+        sessionSummaries: { created: [], skipped: [], overwritten: [], failed: [] },
+    };
+    const written = input.service.transaction(() => {
+        for (const [index, observation] of packageValue.observations.entries()) {
+            const prepared = prepareObservation(observation, packageValue.migrationBatchId, index);
+            const existing = input.service.observations.getByTopic(prepared);
+            if (!existing.ok && existing.error.code !== 'not_found') {
+                summary.counts.observations.failed += 1;
+                summary.observations.failed.push({ ...identity(prepared), message: existing.error.message });
+                return { ok: false, error: existing.error };
+            }
+            if (existing.ok && input.duplicatePolicy === 'skip-existing') {
+                summary.counts.observations.skipped += 1;
+                summary.observations.skipped.push({ id: existing.value.id, ...identity(prepared) });
+                continue;
+            }
+            const saved = input.service.saveObservation(prepared, context);
+            if (!saved.ok) {
+                summary.counts.observations.failed += 1;
+                summary.observations.failed.push({ ...identity(prepared), message: saved.error.message });
+                return { ok: false, error: saved.error };
+            }
+            if (existing.ok) {
+                summary.counts.observations.overwritten += 1;
+                summary.observations.overwritten.push({ id: saved.value.id, ...identity(prepared) });
+            }
+            else {
+                summary.counts.observations.created += 1;
+                summary.observations.created.push({ id: saved.value.id, ...identity(prepared) });
+            }
+        }
+        const sdd = new SddWorkflowService(input.service, context);
+        for (const artifact of packageValue.sddArtifacts ?? []) {
+            const prepared = prepareSddArtifact(artifact, packageValue.migrationBatchId);
+            const existing = input.service.getArtifactNoTrace(prepared.project, prepared.topicKey);
+            if (!existing.ok && existing.error.code !== 'not_found') {
+                summary.counts.sddArtifacts.failed += 1;
+                summary.sddArtifacts.failed.push({ ...artifactIdentity(prepared), message: existing.error.message });
+                return { ok: false, error: existing.error };
+            }
+            if (existing.ok && input.duplicatePolicy === 'skip-existing') {
+                summary.counts.sddArtifacts.skipped += 1;
+                summary.sddArtifacts.skipped.push({ id: existing.value.id, ...artifactIdentity(prepared) });
+                continue;
+            }
+            const saved = sdd.saveArtifact(prepared);
+            if (!saved.ok) {
+                summary.counts.sddArtifacts.failed += 1;
+                summary.sddArtifacts.failed.push({ ...artifactIdentity(prepared), message: saved.error.message });
+                return { ok: false, error: saved.error };
+            }
+            if (existing.ok) {
+                summary.counts.sddArtifacts.overwritten += 1;
+                summary.sddArtifacts.overwritten.push({ id: saved.value.id, ...artifactIdentity(prepared) });
+            }
+            else {
+                summary.counts.sddArtifacts.created += 1;
+                summary.sddArtifacts.created.push({ id: saved.value.id, ...artifactIdentity(prepared) });
+            }
+        }
+        for (const [index, sessionSummary] of (packageValue.sessionSummaries ?? []).entries()) {
+            const prepared = prepareSessionSummary(sessionSummary, packageValue.migrationBatchId, index);
+            const existing = getExistingSessionSummary(input.service, prepared);
+            if (!existing.ok && existing.error.code !== 'not_found') {
+                summary.counts.sessionSummaries.failed += 1;
+                summary.sessionSummaries.failed.push({ ...identity(prepared), message: existing.error.message });
+                return { ok: false, error: existing.error };
+            }
+            if (existing.ok && input.duplicatePolicy === 'skip-existing') {
+                summary.counts.sessionSummaries.skipped += 1;
+                summary.sessionSummaries.skipped.push({ id: existing.value.id, ...identity(prepared) });
+                continue;
+            }
+            const saved = existing.ok && input.duplicatePolicy === 'overwrite'
+                ? input.service.updateObservation({ id: existing.value.id, type: prepared.type, title: prepared.title, content: prepared.content, topicKey: prepared.topicKey }, context)
+                : input.service.saveObservation(prepared, context);
+            if (!saved.ok) {
+                summary.counts.sessionSummaries.failed += 1;
+                summary.sessionSummaries.failed.push({ ...identity(prepared), message: saved.error.message });
+                return { ok: false, error: saved.error };
+            }
+            if (existing.ok) {
+                summary.counts.sessionSummaries.overwritten += 1;
+                summary.sessionSummaries.overwritten.push({ id: saved.value.id, ...identity(prepared) });
+            }
+            else {
+                summary.counts.sessionSummaries.created += 1;
+                summary.sessionSummaries.created.push({ id: saved.value.id, ...identity(prepared) });
+            }
+        }
+        return { ok: true, value: summary };
+    });
+    return written.ok ? { ok: true, value: written.value } : written;
+}
+function emptyCounts() {
+    return { created: 0, skipped: 0, overwritten: 0, rejected: 0, failed: 0 };
+}
+function prepareObservation(observation, migrationBatchId, index) {
+    const topicKey = observation.topicKey ?? generatedTopicKey(observation, migrationBatchId, index);
+    return {
+        project: observation.project,
+        scope: observation.scope,
+        type: observation.type,
+        title: observation.title,
+        content: withProvenanceBlock(observation.content, observation.source, migrationBatchId),
+        topicKey,
+    };
+}
+function prepareSddArtifact(artifact, migrationBatchId) {
+    return {
+        project: artifact.project,
+        change: artifact.change,
+        phase: artifact.phase,
+        topicKey: sddTopicKey(artifact.change, artifact.phase),
+        content: withProvenanceBlock(artifact.content, artifact.source, migrationBatchId, 'sddArtifact'),
+    };
+}
+function prepareSessionSummary(summary, migrationBatchId, index) {
+    const project = summary.project ?? 'vgxness';
+    const topicKey = summary.topicKey ?? sessionSummaryTopicKey(summary, migrationBatchId, index);
+    const sessionIdentity = summary.sourceSessionId ?? summary.sessionId ?? summary.source?.sessionId;
+    return {
+        project,
+        scope: 'project',
+        type: 'manual',
+        title: sessionIdentity === undefined ? `Imported session summary ${index + 1}` : `Imported session summary ${sessionIdentity}`,
+        content: withProvenanceBlock(summary.content, sessionSummaryProvenance(summary), migrationBatchId, 'sessionSummary'),
+        topicKey,
+    };
+}
+function getExistingSessionSummary(service, prepared) {
+    const found = service.observations.search({ project: prepared.project, scope: prepared.scope, topicKey: prepared.topicKey, limit: 1 });
+    if (!found.ok)
+        return found;
+    const [existing] = found.value;
+    if (existing === undefined)
+        return { ok: false, error: { code: 'not_found', message: `Session summary topic not found: ${prepared.topicKey}` } };
+    return { ok: true, value: existing };
+}
+function sessionSummaryProvenance(summary) {
+    return stripUndefined({ ...summary.source, sourceSessionId: summary.sourceSessionId, sessionId: summary.sessionId });
+}
+function generatedTopicKey(observation, migrationBatchId, index) {
+    const sourceId = observation.source?.id ?? observation.source?.sourceId;
+    if (sourceId !== undefined && sourceId.trim().length > 0)
+        return `migrated/engram/${slug(sourceId)}`;
+    return `migrated/engram/${slug(migrationBatchId)}/observation-${index + 1}-${slug(observation.title)}`;
+}
+function sessionSummaryTopicKey(summary, migrationBatchId, index) {
+    const sourceSessionId = summary.sourceSessionId ?? summary.sessionId ?? summary.source?.sessionId;
+    if (sourceSessionId !== undefined && sourceSessionId.trim().length > 0)
+        return `migrated/engram/session-summary/${slug(sourceSessionId)}`;
+    const sourceId = summary.source?.id ?? summary.source?.sourceId;
+    if (sourceId !== undefined && sourceId.trim().length > 0)
+        return `migrated/engram/session-summary/${slug(sourceId)}`;
+    return `migrated/engram/${slug(migrationBatchId)}/session-summary-${index + 1}`;
+}
+function withProvenanceBlock(content, sourceProvenance, migrationBatchId, provenanceKey = 'observation') {
+    const provenance = stableJson({
+        migrationBatchId,
+        source: 'engram',
+        [provenanceKey]: sourceProvenance ?? {},
+    });
+    const block = `\n\n<!-- vgxness-memory-import ${provenance} -->`;
+    return content.endsWith(block) ? content : `${content}${block}`;
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+function identity(observation) {
+    return { project: observation.project, scope: observation.scope, type: observation.type, topicKey: observation.topicKey };
+}
+function artifactIdentity(artifact) {
+    return { project: artifact.project, change: artifact.change, phase: artifact.phase, topicKey: artifact.topicKey };
+}
+function stableJson(value) {
+    return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortJson);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, sortJson(item)]));
+}
+function slug(value) {
+    const normalized = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return normalized.length > 0 ? normalized : 'untitled';
+}
+function formatValidationErrors(errors) {
+    return errors.map((error) => `${error.path}: ${error.message}`).join('; ');
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}

package/dist/memory/import/package.js

@@ -0,0 +1,178 @@
+import { isSddPhase, sddPhases, sddTopicKey } from '../../sdd/schema.js';
+export const MEMORY_IMPORT_PACKAGE_KIND = 'vgxness.memory-import-package';
+export const MEMORY_IMPORT_PACKAGE_VERSION = 1;
+export const MEMORY_IMPORT_PACKAGE_SOURCE = 'engram';
+const scopes = ['project', 'personal'];
+const provenanceStringFields = ['system', 'id', 'sourceId', 'createdAt', 'updatedAt', 'sessionId'];
+export function validateMemoryImportPackage(input) {
+    const errors = [];
+    if (!isRecord(input)) {
+        return { ok: false, errors: [{ path: '$', message: 'package must be an object' }] };
+    }
+    requireExact(input, 'kind', MEMORY_IMPORT_PACKAGE_KIND, errors, 'unsupported package kind');
+    validateVersion(input.version, errors);
+    requireExact(input, 'source', MEMORY_IMPORT_PACKAGE_SOURCE, errors, 'unsupported package source');
+    requireNonEmptyString(input, 'exportedAt', errors);
+    requireNonEmptyString(input, 'migrationBatchId', errors);
+    if (input.observations === undefined) {
+        errors.push({ path: 'observations', message: 'observations is required' });
+    }
+    else if (!Array.isArray(input.observations)) {
+        errors.push({ path: 'observations', message: 'observations must be an array' });
+    }
+    else {
+        input.observations.forEach((item, index) => validateObservation(item, index, errors));
+    }
+    if (input.sddArtifacts !== undefined) {
+        if (!Array.isArray(input.sddArtifacts)) {
+            errors.push({ path: 'sddArtifacts', message: 'sddArtifacts must be an array when present' });
+        }
+        else {
+            input.sddArtifacts.forEach((item, index) => validateSddArtifact(item, index, errors));
+        }
+    }
+    if (input.sessionSummaries !== undefined) {
+        if (!Array.isArray(input.sessionSummaries)) {
+            errors.push({ path: 'sessionSummaries', message: 'sessionSummaries must be an array when present' });
+        }
+        else {
+            input.sessionSummaries.forEach((item, index) => validateSessionSummary(item, index, errors));
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, package: input };
+}
+function validateObservation(input, index, errors) {
+    const path = `observations[${index}]`;
+    if (!isRecord(input)) {
+        errors.push({ path, index, message: 'observation must be an object' });
+        return;
+    }
+    requireNonEmptyString(input, 'project', errors, path, index);
+    requireOneOf(input, 'scope', scopes, errors, path, index);
+    requireNonEmptyString(input, 'type', errors, path, index);
+    requireNonEmptyString(input, 'title', errors, path, index);
+    requireNonEmptyString(input, 'content', errors, path, index);
+    optionalNonEmptyString(input, 'topicKey', errors, path, index);
+    validateOptionalProvenance(input, path, index, errors);
+}
+function validateSddArtifact(input, index, errors) {
+    const path = `sddArtifacts[${index}]`;
+    if (!isRecord(input)) {
+        errors.push({ path, index, message: 'SDD artifact must be an object' });
+        return;
+    }
+    requireNonEmptyString(input, 'project', errors, path, index);
+    requireNonEmptyString(input, 'change', errors, path, index);
+    const phase = requireSddPhase(input, errors, path, index);
+    requireNonEmptyString(input, 'content', errors, path, index);
+    optionalNonEmptyString(input, 'topicKey', errors, path, index);
+    validateOptionalProvenance(input, path, index, errors);
+    if (typeof input.topicKey === 'string' && typeof input.change === 'string' && phase !== undefined) {
+        const expected = sddTopicKey(input.change, phase);
+        if (input.topicKey !== expected) {
+            errors.push({ path: `${path}.topicKey`, index, message: `topicKey must match canonical SDD topic key ${expected}` });
+        }
+    }
+}
+function validateSessionSummary(input, index, errors) {
+    const path = `sessionSummaries[${index}]`;
+    if (!isRecord(input)) {
+        errors.push({ path, index, message: 'session summary must be an object' });
+        return;
+    }
+    requireNonEmptyString(input, 'content', errors, path, index);
+    optionalNonEmptyString(input, 'project', errors, path, index);
+    optionalNonEmptyString(input, 'type', errors, path, index);
+    optionalNonEmptyString(input, 'sourceSessionId', errors, path, index);
+    optionalNonEmptyString(input, 'sessionId', errors, path, index);
+    optionalNonEmptyString(input, 'topicKey', errors, path, index);
+    validateOptionalProvenance(input, path, index, errors);
+}
+function validateVersion(value, errors) {
+    if (value === undefined) {
+        errors.push({ path: 'version', message: 'version is required' });
+        return;
+    }
+    if (value !== MEMORY_IMPORT_PACKAGE_VERSION) {
+        errors.push({ path: 'version', message: `unsupported package version; expected version ${MEMORY_IMPORT_PACKAGE_VERSION}; received ${renderReceivedValue(value)}` });
+    }
+}
+function requireExact(record, field, expected, errors, message) {
+    if (record[field] === undefined) {
+        errors.push({ path: field, message: `${field} is required` });
+        return;
+    }
+    if (record[field] !== expected) {
+        errors.push({ path: field, message: `${message}; expected ${expected}; received ${renderReceivedValue(record[field])}` });
+    }
+}
+function renderReceivedValue(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+        ? String(value)
+        : 'provided value';
+}
+function requireNonEmptyString(record, field, errors, parentPath, index) {
+    const path = parentPath === undefined ? field : `${parentPath}.${field}`;
+    if (record[field] === undefined) {
+        pushError(errors, path, `${field} is required`, index);
+        return undefined;
+    }
+    if (typeof record[field] !== 'string') {
+        pushError(errors, path, `${field} must be a string`, index);
+        return undefined;
+    }
+    if (record[field].trim().length === 0) {
+        pushError(errors, path, `${field} must not be empty`, index);
+        return undefined;
+    }
+    return record[field];
+}
+function optionalNonEmptyString(record, field, errors, parentPath, index) {
+    if (record[field] === undefined)
+        return;
+    requireNonEmptyString(record, field, errors, parentPath, index);
+}
+function requireOneOf(record, field, values, errors, parentPath, index) {
+    const value = requireNonEmptyString(record, field, errors, parentPath, index);
+    if (value === undefined)
+        return undefined;
+    if (!values.includes(value)) {
+        errors.push({ path: `${parentPath}.${field}`, index, message: `${field} must be one of: ${values.join(', ')}` });
+        return undefined;
+    }
+    return value;
+}
+function requireSddPhase(record, errors, parentPath, index) {
+    const value = requireNonEmptyString(record, 'phase', errors, parentPath, index);
+    if (value === undefined)
+        return undefined;
+    if (!isSddPhase(value)) {
+        errors.push({ path: `${parentPath}.phase`, index, message: `phase must be one of: ${sddPhases.join(', ')}` });
+        return undefined;
+    }
+    return value;
+}
+function validateOptionalProvenance(record, parentPath, index, errors) {
+    if (record.source === undefined)
+        return;
+    if (!isRecord(record.source)) {
+        errors.push({ path: `${parentPath}.source`, index, message: 'source must be an object when present' });
+        return;
+    }
+    for (const field of provenanceStringFields) {
+        if (record.source[field] !== undefined && typeof record.source[field] !== 'string') {
+            errors.push({ path: `${parentPath}.source.${field}`, index, message: `${field} must be a string when present` });
+        }
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function pushError(errors, path, message, index) {
+    const error = { path, message };
+    if (index !== undefined)
+        error.index = index;
+    errors.push(error);
+}

package/dist/memory/memory-service.js

@@ -0,0 +1,126 @@
+import { ArtifactRepository } from './repositories/artifacts.js';
+import { ObservationRepository } from './repositories/observations.js';
+import { SessionRepository } from './repositories/sessions.js';
+import { TraceRepository } from './repositories/traces.js';
+export class MemoryService {
+    database;
+    observations;
+    sessions;
+    artifacts;
+    traces;
+    constructor(database) {
+        this.database = database;
+        this.observations = new ObservationRepository(database);
+        this.sessions = new SessionRepository(database);
+        this.artifacts = new ArtifactRepository(database);
+        this.traces = new TraceRepository(database);
+    }
+    transaction(operation) {
+        let failure;
+        const result = this.database.transaction(() => {
+            const operationResult = operation();
+            if (!operationResult.ok) {
+                failure = operationResult;
+                throw new MemoryServiceTransactionRollback();
+            }
+            return operationResult.value;
+        });
+        if (!result.ok)
+            return failure ?? result;
+        return { ok: true, value: result.value };
+    }
+    saveObservation(input, context) {
+        const result = this.observations.save(input);
+        return this.record(result, context, { operation: input.topicKey ? 'observation.upsert' : 'observation.save', targetType: 'observation', targetId: result.ok ? result.value.id : undefined, topicKey: input.topicKey });
+    }
+    getObservation(id, context) {
+        const result = this.observations.getById(id);
+        return this.record(result, context, { operation: 'observation.get', targetType: 'observation', targetId: id });
+    }
+    updateObservation(input, context) {
+        const result = this.observations.update(input);
+        return this.record(result, context, { operation: 'observation.update', targetType: 'observation', targetId: input.id, topicKey: input.topicKey });
+    }
+    searchObservations(filters, context) {
+        const result = this.observations.searchPreviews(filters);
+        return this.record(result, context, { operation: 'observation.search', targetType: 'observation', topicKey: filters.topicKey });
+    }
+    listObservationRevisions(id, context) {
+        const result = this.observations.listRevisions(id);
+        return this.record(result, context, { operation: 'observation.revisions.list', targetType: 'observation', targetId: id });
+    }
+    saveSession(input, context) {
+        const result = this.sessions.save(input);
+        return this.record(result, context, { operation: 'session.save', targetType: 'session', targetId: result.ok ? result.value.id : input.id });
+    }
+    appendActivity(input, context) {
+        const result = this.sessions.appendActivity(input);
+        return this.record(result, context, { operation: 'session.activity.append', targetType: 'session_activity', targetId: result.ok ? result.value.id : input.sessionId });
+    }
+    closeSession(input, context) {
+        const result = this.sessions.closeSession(input);
+        return this.record(result, context, { operation: 'session.close', targetType: 'session', targetId: input.sessionId });
+    }
+    /** Read the latest closed session summary without writing provenance traces. */
+    restoreSession(input) {
+        return this.sessions.restoreLatest(input);
+    }
+    saveArtifact(input, context) {
+        const observation = this.saveObservation({ project: input.project, scope: 'project', type: 'sdd-artifact', title: input.topicKey, content: input.content, topicKey: input.topicKey }, context);
+        if (!observation.ok)
+            return observation;
+        const result = this.artifacts.save({ ...input, observationId: observation.value.id });
+        return this.record(result, context, { operation: 'artifact.save', targetType: 'artifact', targetId: result.ok ? result.value.id : undefined, topicKey: input.topicKey });
+    }
+    getArtifact(project, topicKey, context) {
+        const result = this.artifacts.getByTopic(project, topicKey);
+        return this.record(result, context, { operation: 'artifact.get', targetType: 'artifact', targetId: result.ok ? result.value.id : undefined, topicKey });
+    }
+    /**
+     * Read an artifact without writing a trace. This is only for read-only UI/status
+     * boundaries that must not mutate memory while checking local artifact state.
+     */
+    getArtifactNoTrace(project, topicKey) {
+        return this.artifacts.getByTopic(project, topicKey);
+    }
+    /**
+     * Check artifact presence without writing a trace. Missing artifacts are a
+     * successful `false` result so callers can distinguish absence from store errors.
+     */
+    hasArtifactNoTrace(project, topicKey) {
+        const artifact = this.getArtifactNoTrace(project, topicKey);
+        if (artifact.ok)
+            return { ok: true, value: true };
+        if (artifact.error.code === 'not_found')
+            return { ok: true, value: false };
+        return artifact;
+    }
+    listArtifactsByTopicPrefix(project, topicPrefix, context) {
+        const result = this.artifacts.listByTopicPrefix(project, topicPrefix);
+        return this.record(result, context, { operation: 'artifact.list', targetType: 'artifact', topicKey: topicPrefix });
+    }
+    close() { this.database.close(); }
+    record(result, context, parts) {
+        this.trace(context, { ...parts, status: result.ok ? 'ok' : 'error', error: result.ok ? undefined : result.error });
+        return result;
+    }
+    trace(context, parts) {
+        const input = { actor: context.actor, operation: parts.operation, targetType: parts.targetType, status: parts.status };
+        if (context.sessionId !== undefined)
+            input.sessionId = context.sessionId;
+        if (parts.targetId !== undefined)
+            input.targetId = parts.targetId;
+        if (parts.topicKey !== undefined)
+            input.topicKey = parts.topicKey;
+        if (parts.error !== undefined) {
+            input.errorCode = parts.error.code;
+            input.errorMessage = parts.error.message;
+        }
+        this.traces.write(input);
+    }
+}
+class MemoryServiceTransactionRollback extends Error {
+    constructor() {
+        super('Memory service transaction rolled back');
+    }
+}

package/dist/memory/repositories/artifacts.js

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+export class ArtifactRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    save(input) {
+        const result = this.db.transaction(() => {
+            const existing = this.db.connection.prepare('SELECT * FROM artifacts WHERE project=@project AND topic_key=@topicKey').get(input);
+            const now = new Date().toISOString();
+            this.db.connection.prepare(`INSERT INTO artifacts(id, project, topic_key, phase, content, observation_id, created_at, updated_at)
+        VALUES (@id, @project, @topicKey, @phase, @content, @observationId, @createdAt, @updatedAt)
+        ON CONFLICT(project, topic_key) DO UPDATE SET phase=excluded.phase, content=excluded.content, observation_id=excluded.observation_id, updated_at=excluded.updated_at`).run({ ...input, id: existing?.id ?? randomUUID(), createdAt: existing?.created_at ?? now, updatedAt: now });
+            const artifact = this.getByTopic(input.project, input.topicKey);
+            if (!artifact.ok)
+                throw new Error(artifact.error.message);
+            return artifact.value;
+        });
+        return result.ok ? result : fail(result.error.message, result.error.cause);
+    }
+    getByTopic(project, topicKey) {
+        try {
+            const row = this.db.connection.prepare('SELECT * FROM artifacts WHERE project=? AND topic_key=?').get(project, topicKey);
+            return row ? { ok: true, value: map(row) } : { ok: false, error: { code: 'not_found', message: `Artifact not found: ${topicKey}` } };
+        }
+        catch (cause) {
+            return fail('Failed to read artifact', cause);
+        }
+    }
+    listByTopicPrefix(project, topicPrefix) {
+        try {
+            const rows = this.db.connection.prepare('SELECT * FROM artifacts WHERE project=? AND topic_key LIKE ? ORDER BY topic_key ASC').all(project, `${topicPrefix}%`);
+            return { ok: true, value: rows.map(map).filter((artifact) => artifact.topicKey.startsWith(topicPrefix)) };
+        }
+        catch (cause) {
+            return fail('Failed to list artifacts', cause);
+        }
+    }
+}
+function map(row) { return { id: row.id, project: row.project, topicKey: row.topic_key, phase: row.phase, content: row.content, observationId: row.observation_id, createdAt: row.created_at, updatedAt: row.updated_at }; }
+function fail(message, cause) { return { ok: false, error: { code: 'validation_failed', message, cause } }; }