brainclaw 0.29.2 → 1.5.4

package/dist/core/upgrades/patches/provenance-rollout.js

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+/**
+ * Provenance rollout (P6.3) — v1.0 schema migration patch.
+ *
+ * Stamps every pre-existing memory record with a `provenance` field
+ * of kind `legacy`. From v1.0 onward, write paths populate the
+ * typed discriminated-union provenance (agent / auto_reflect / user /
+ * loop_artifact / federation / correction / legacy); legacy records
+ * keep the `legacy` tag so default read filters can exclude them
+ * until an operator promotes them.
+ *
+ * Scope: decisions, constraints, traps, handoffs, runtime_notes.
+ *
+ * Auto-reflect retroactive detection: not attempted. Pre-v1.0 records
+ * do not carry a reliable marker distinguishing auto-reflect writes
+ * from human-authored writes at the entity level. Stamping every
+ * pre-existing record as `legacy` is the safe default — new
+ * auto-reflect writes from v1.0 onward carry the correct provenance
+ * from birth.
+ *
+ * Like the other patches, implementation uses raw JSON read/write
+ * (no Zod round-trip) so unknown fields survive the rewrite.
+ */
+export const MIGRATIONS_ARCHIVE_SUBPATH = path.join('archive', 'migrations');
+export const PROVENANCE_ROLLOUT_LOG = 'provenance-rollout.json';
+export const PROVENANCE_ENTITY_LAYOUTS = [
+    { kind: 'decision', dir: path.join('memory', 'decisions'), recursive: false },
+    { kind: 'constraint', dir: path.join('memory', 'constraints'), recursive: false },
+    { kind: 'trap', dir: path.join('memory', 'traps'), recursive: false },
+    { kind: 'handoff', dir: path.join('coordination', 'handoffs'), recursive: false },
+    { kind: 'runtime_note', dir: path.join('coordination', 'runtime'), recursive: true },
+];
+export const ProvenanceRolloutEntrySchema = z.object({
+    kind: z.enum(['decision', 'constraint', 'trap', 'handoff', 'runtime_note']),
+    id: z.string(),
+    short_label: z.string().nullable(),
+    record_path: z.string(),
+    stamped_kind: z.literal('legacy'),
+    stamped_at: z.string().datetime(),
+});
+export const ProvenanceRolloutLogSchema = z.object({
+    schema_version: z.literal(1),
+    stamped_at: z.string().datetime(),
+    reason: z.string(),
+    count: z.number().int().nonnegative(),
+    counts_by_kind: z.record(z.string(), z.number().int().nonnegative()),
+    entries: z.array(ProvenanceRolloutEntrySchema),
+});
+export function rolloutProvenance(options) {
+    const { storePath } = options;
+    const now = (options.now ?? (() => new Date()))();
+    const dateStamp = now.toISOString().slice(0, 10);
+    const logDir = path.join(storePath, MIGRATIONS_ARCHIVE_SUBPATH, dateStamp);
+    const logPath = path.join(logDir, PROVENANCE_ROLLOUT_LOG);
+    const reason = options.reason ?? 'v1.0 schema migration (P6.3): stamp legacy provenance on pre-existing memory records';
+    let scanned = 0;
+    const entries = [];
+    const countsByKind = {};
+    for (const layout of PROVENANCE_ENTITY_LAYOUTS) {
+        const fullDir = path.join(storePath, layout.dir);
+        const files = listJsonFiles(fullDir, layout.recursive);
+        scanned += files.length;
+        for (const file of files) {
+            const raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+                throw new Error(`provenance-rollout: ${file} is not a JSON object`);
+            }
+            const obj = raw;
+            if (obj.provenance !== undefined) {
+                if (isValidV1Provenance(obj.provenance))
+                    continue;
+                throw new Error(`provenance-rollout: ${file} has a malformed \`provenance\` field; ` +
+                    `expected an object with a known kind, got ${JSON.stringify(obj.provenance)}`);
+            }
+            const entry = {
+                kind: layout.kind,
+                id: typeof obj.id === 'string' ? obj.id : path.basename(file, '.json'),
+                short_label: typeof obj.short_label === 'string' ? obj.short_label : null,
+                record_path: path.relative(storePath, file).split(path.sep).join('/'),
+                stamped_kind: 'legacy',
+                stamped_at: now.toISOString(),
+            };
+            entries.push(entry);
+            countsByKind[layout.kind] = (countsByKind[layout.kind] ?? 0) + 1;
+            if (!options.dryRun) {
+                const next = { ...obj, provenance: { kind: 'legacy' } };
+                fs.writeFileSync(file, JSON.stringify(next, null, 2), 'utf-8');
+            }
+        }
+    }
+    if (entries.length === 0) {
+        return { status: 'noop', scanned, stamped: [], countsByKind, logPath: null };
+    }
+    if (options.dryRun) {
+        return { status: 'planned', scanned, stamped: entries, countsByKind, logPath };
+    }
+    fs.mkdirSync(logDir, { recursive: true });
+    const log = {
+        schema_version: 1,
+        stamped_at: now.toISOString(),
+        reason,
+        count: entries.length,
+        counts_by_kind: countsByKind,
+        entries,
+    };
+    fs.writeFileSync(logPath, JSON.stringify(log, null, 2), 'utf-8');
+    return { status: 'stamped', scanned, stamped: entries, countsByKind, logPath };
+}
+const V1_PROVENANCE_KINDS = new Set([
+    'agent', 'auto_reflect', 'user', 'loop_artifact', 'federation', 'correction', 'legacy',
+]);
+function isValidV1Provenance(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const kind = value.kind;
+    return typeof kind === 'string' && V1_PROVENANCE_KINDS.has(kind);
+}
+function listJsonFiles(dir, recursive) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isFile() && entry.name.endsWith('.json')) {
+            out.push(full);
+            continue;
+        }
+        if (recursive && entry.isDirectory()) {
+            out.push(...listJsonFiles(full, true));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=provenance-rollout.js.map

package/dist/core/upgrades/schema-version.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { writeFileAtomic } from '../io.js';
+/**
+ * Store schema version tracker — distinct from the MCP SCHEMA_VERSION
+ * constant (which tracks what the *server* expects). This file tracks
+ * what the *store* is currently at.
+ *
+ * Lives at `.brainclaw/schema-version.json`. Absent = implicit 0.6.0
+ * (the pre-migration baseline).
+ *
+ * The history trail records every upgrade transition so an operator
+ * can audit what ran, when, and which patches landed — useful when
+ * dogfooding across two installations and comparing them.
+ */
+export const SCHEMA_VERSION_FILE = 'schema-version.json';
+/** Implicit baseline when `.brainclaw/schema-version.json` is absent. */
+export const IMPLICIT_BASELINE_VERSION = '0.6.0';
+/** Known store schema states for the v1 upgrade/rollback flow. */
+export const KNOWN_STORE_SCHEMA_VERSIONS = [IMPLICIT_BASELINE_VERSION, '0.7.0', '0.8.0'];
+/** Target of a `--to=1.0` upgrade (migration-complete marker). */
+export const V1_TARGET_SCHEMA_VERSION = '0.8.0';
+export const SchemaVersionTransitionSchema = z.object({
+    from: z.string(),
+    to: z.string(),
+    at: z.string().datetime(),
+    patches: z.array(z.string()),
+    reason: z.string().optional(),
+});
+export const SchemaVersionFileSchema = z.object({
+    schema_version: z.literal(1),
+    current: z.string(),
+    history: z.array(SchemaVersionTransitionSchema),
+});
+export function schemaVersionFilePath(storePath) {
+    return path.join(storePath, SCHEMA_VERSION_FILE);
+}
+export function readSchemaVersion(storePath) {
+    const file = schemaVersionFilePath(storePath);
+    if (!fs.existsSync(file)) {
+        return { present: false, current: IMPLICIT_BASELINE_VERSION, history: [] };
+    }
+    const raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    const parsed = SchemaVersionFileSchema.parse(raw);
+    return { present: true, current: parsed.current, history: parsed.history };
+}
+/**
+ * Record a schema-version transition. Idempotent — if the store is
+ * already at the target version the call is a noop. Otherwise,
+ * appends a transition entry to the history and writes the file
+ * atomically.
+ */
+export function bumpSchemaVersion(options) {
+    const now = (options.now ?? (() => new Date()))();
+    const file = schemaVersionFilePath(options.storePath);
+    const existing = readSchemaVersion(options.storePath);
+    if (existing.current === options.to) {
+        return {
+            status: 'noop',
+            from: existing.current,
+            to: options.to,
+            filePath: file,
+            transitions: existing.history.length,
+        };
+    }
+    if (options.dryRun) {
+        return {
+            status: 'planned',
+            from: existing.current,
+            to: options.to,
+            filePath: file,
+            transitions: existing.history.length + 1,
+        };
+    }
+    const transition = {
+        from: existing.current,
+        to: options.to,
+        at: now.toISOString(),
+        patches: options.patches,
+        reason: options.reason,
+    };
+    const next = {
+        schema_version: 1,
+        current: options.to,
+        history: [...existing.history, transition],
+    };
+    writeFileAtomic(file, JSON.stringify(next, null, 2));
+    return {
+        status: 'bumped',
+        from: existing.current,
+        to: options.to,
+        filePath: file,
+        transitions: next.history.length,
+    };
+}
+//# sourceMappingURL=schema-version.js.map