@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/scripts/memory-lifecycle.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env tsx
+/**
+ * Explicit opt-in memory lifecycle collector CLI (issue #228).
+ *
+ * The production CLI intentionally has no --at flag: timestamps come from the
+ * local clock. Tests inject clocks through ../src/memory-lifecycle.ts instead.
+ */
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { completeMemoryLifecycleFlow, endExternalWait, exportMemoryLifecycleFixture, initMemoryLifecycleDataset, MemoryLifecycleError, recordExperienceReflux, recordPreferenceAssertion, startExternalWait, startMemoryLifecycleFlow, } from '../src/memory-lifecycle.js';
+const ERROR_MESSAGES = {
+    bad_args: 'bad_args',
+    dataset_already_initialized: 'dataset_already_initialized',
+    dataset_consent_mismatch: 'dataset_consent_mismatch',
+    dataset_key_mismatch: 'dataset_key_mismatch',
+    dataset_not_initialized: 'dataset_not_initialized',
+    dataset_source_mismatch: 'dataset_source_mismatch',
+    flow_limit_reached: 'flow_limit_reached',
+    internal_error: 'internal_error',
+    invalid_hmac_key: 'invalid_hmac_key',
+    invalid_input: 'invalid_input',
+    invalid_store: 'invalid_store',
+    invalid_transition: 'invalid_transition',
+    lock_busy: 'lock_busy',
+    missing_consent: 'missing_consent',
+    missing_hmac_key: 'missing_hmac_key',
+    missing_state_root: 'missing_state_root',
+    output_exists: 'output_exists',
+    unsafe_state_root: 'unsafe_state_root',
+};
+function parseFlags(args) {
+    const [command, ...rest] = args;
+    if (!command)
+        throw new MemoryLifecycleError('bad_args');
+    const flags = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const token = rest[index];
+        if (!token.startsWith('--'))
+            throw new MemoryLifecycleError('bad_args');
+        const key = token.slice(2);
+        if (!key)
+            throw new MemoryLifecycleError('bad_args');
+        const next = rest[index + 1];
+        const value = next === undefined || next.startsWith('--') ? true : (index += 1, next);
+        if (key in flags) {
+            const current = flags[key];
+            flags[key] = Array.isArray(current) ? [...current, value] : [current, value];
+        }
+        else {
+            flags[key] = value;
+        }
+    }
+    return { command, flags };
+}
+function one(flags, key, required = true) {
+    const value = flags[key];
+    if (Array.isArray(value) || value === true)
+        throw new MemoryLifecycleError('bad_args');
+    if (value === undefined && required)
+        throw new MemoryLifecycleError(key === 'state-root' ? 'missing_state_root' : 'invalid_input');
+    return value;
+}
+function many(flags, key) {
+    const value = flags[key];
+    if (value === undefined)
+        return [];
+    if (value === true)
+        throw new MemoryLifecycleError('bad_args');
+    return Array.isArray(value) ? value.map(item => {
+        if (item === true)
+            throw new MemoryLifecycleError('bad_args');
+        return item;
+    }) : [value];
+}
+function common(flags) {
+    const stateRoot = one(flags, 'state-root');
+    const consent = one(flags, 'consent', false);
+    if (!consent)
+        throw new MemoryLifecycleError('missing_consent');
+    return {
+        stateRoot: stateRoot,
+        consent,
+        hmacKey: process.env.GOTRY_MEMORY_LIFECYCLE_HMAC_KEY,
+    };
+}
+function ensureNoUnknownFlags(flags, allowed) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(flags)) {
+        if (!allowedSet.has(key))
+            throw new MemoryLifecycleError('bad_args');
+    }
+}
+function output(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function run(command, flags) {
+    switch (command) {
+        case 'init': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'source', 'dataset', 'wait-code']);
+            const source = one(flags, 'source');
+            if (source !== 'synthetic_fixture' && source !== 'observed_private')
+                throw new MemoryLifecycleError('invalid_input');
+            output(initMemoryLifecycleDataset({
+                ...common(flags),
+                sourceKind: source,
+                dataset: one(flags, 'dataset'),
+                waitCodes: many(flags, 'wait-code'),
+            }));
+            return;
+        }
+        case 'start': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'subject', 'flow', 'eligible-planning']);
+            if (flags['eligible-planning'] !== true)
+                throw new MemoryLifecycleError('invalid_input');
+            output(startMemoryLifecycleFlow({ ...common(flags), subject: one(flags, 'subject'), flow: one(flags, 'flow') }));
+            return;
+        }
+        case 'wait-start': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'subject', 'flow', 'wait', 'code']);
+            output(startExternalWait({
+                ...common(flags),
+                subject: one(flags, 'subject'),
+                flow: one(flags, 'flow'),
+                wait: one(flags, 'wait'),
+                code: one(flags, 'code'),
+            }));
+            return;
+        }
+        case 'wait-end': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'subject', 'flow', 'wait']);
+            output(endExternalWait({
+                ...common(flags),
+                subject: one(flags, 'subject'),
+                flow: one(flags, 'flow'),
+                wait: one(flags, 'wait'),
+            }));
+            return;
+        }
+        case 'complete': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'subject', 'flow']);
+            output(completeMemoryLifecycleFlow({ ...common(flags), subject: one(flags, 'subject'), flow: one(flags, 'flow') }));
+            return;
+        }
+        case 'record-reflux': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'experience', 'kind', 'evidence']);
+            const kind = one(flags, 'kind');
+            if (kind !== 'recalled' && kind !== 'verified_outcome')
+                throw new MemoryLifecycleError('invalid_input');
+            output(recordExperienceReflux({
+                ...common(flags),
+                experience: one(flags, 'experience'),
+                kind,
+                evidence: one(flags, 'evidence'),
+            }));
+            return;
+        }
+        case 'record-preference': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'assertion', 'evidence', 'consumer']);
+            const consumer = one(flags, 'consumer');
+            if (consumer !== 'ranking' && consumer !== 'explanation')
+                throw new MemoryLifecycleError('invalid_input');
+            output(recordPreferenceAssertion({
+                ...common(flags),
+                assertion: one(flags, 'assertion'),
+                evidence: one(flags, 'evidence'),
+                consumer,
+            }));
+            return;
+        }
+        case 'export': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'out']);
+            const { fixture, result } = exportMemoryLifecycleFixture({ ...common(flags), out: one(flags, 'out', false) });
+            if (one(flags, 'out', false))
+                output(result);
+            else
+                output(fixture);
+            return;
+        }
+        default:
+            throw new MemoryLifecycleError('bad_args');
+    }
+}
+function main() {
+    try {
+        const { command, flags } = parseFlags(process.argv.slice(2));
+        run(command, flags);
+    }
+    catch (error) {
+        const code = error instanceof MemoryLifecycleError ? error.code : 'internal_error';
+        process.stderr.write(`memory_lifecycle_error:${ERROR_MESSAGES[code]}\n`);
+        process.exitCode = 2;
+    }
+}
+const invokedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
+if (import.meta.url === invokedPath)
+    main();

package/dist/scripts/memory-metrics.js

@@ -1,3 +1,17 @@
+/**
+ * 记忆效用指标投影(M4 北极星底座,只读):从 gotry-state 侧车文件聚合
+ * 「下一次出发率」的过程指标与经验回流率基线(M4 exit 要求有基线)。
+ *
+ * 口径(单用户期即固定,多用户期逐用户展开,RFC §6.5 账本化兼容):
+ *  - wish_total / wish_muted:在册与休眠的憧憬数
+ *  - recalled_wishes / verified_wishes:被召回过 ≥1 次 / 拿到 owner 确认结果的 wish 数
+ *  -回流率基线(reflux_baseline)= verified_wishes / max(recalled_wishes,1)
+ *   ——「被召回的憧憬里有多少走到了可验证的现实结果」;数值本身无好坏,
+ *   先有基线,样本起来后才谈目标。
+ *
+ * 运行:cd ts && npx tsx scripts/memory-metrics.ts [stateRoot]
+ * 只读:不改任何状态文件(巡检状态纪律);无数据时优雅空态 exit 0。
+ */
 import { projectUtility } from '../src/memory-utility.js';
 import { decayedConfidence } from '../src/memory-decay.js';
 import { readUtilityEventsWithFallback, readWishPoolWithFallback } from '../src/state-ledger.js';
@@ -5,20 +19,18 @@ const stateRoot = process.argv[2] ?? '.';
 const pool = readWishPoolWithFallback(stateRoot);
 const events = readUtilityEventsWithFallback(stateRoot);
 const projection = projectUtility(events);
-const active = pool.filter((w)=>typeof w.wish_id === 'string');
-const recalledWishes = Object.values(projection).filter((w)=>w.recalled > 0).length;
-const verifiedWishes = Object.values(projection).filter((w)=>w.verified > 0).length;
+const active = pool.filter(w => typeof w.wish_id === 'string');
+const recalledWishes = Object.values(projection).filter(w => w.recalled > 0).length;
+const verifiedWishes = Object.values(projection).filter(w => w.verified > 0).length;
 const refluxBaseline = verifiedWishes / Math.max(recalledWishes, 1);
 console.log('=== GoTry 记忆效用指标(M4 北极星过程面,只读) ===');
-console.log(`wish pool: ${pool.length} 条在册(其中 ${pool.filter((w)=>w.muted).length} 条休眠,${active.length} 条有稳定 wish_id)`);
-console.log(`效用事件: ${events.length} 条(recalled=${events.filter((e)=>e.kind === 'recalled').length}, applied=${events.filter((e)=>e.kind === 'applied').length}, verified=${events.filter((e)=>e.kind === 'verified_outcome').length})`);
-for (const w of Object.values(projection)){
-    const name = pool.find((p)=>p.wish_id === w.wish_id)?.name ?? w.wish_id;
-    const conf = decayedConfidence(events.filter((e)=>e.wish_id === w.wish_id), new Date());
+console.log(`wish pool: ${pool.length} 条在册(其中 ${pool.filter(w => w.muted).length} 条休眠,${active.length} 条有稳定 wish_id)`);
+console.log(`效用事件: ${events.length} 条(recalled=${events.filter(e => e.kind === 'recalled').length}, applied=${events.filter(e => e.kind === 'applied').length}, verified=${events.filter(e => e.kind === 'verified_outcome').length})`);
+for (const w of Object.values(projection)) {
+    const name = pool.find(p => p.wish_id === w.wish_id)?.name ?? w.wish_id;
+    const conf = decayedConfidence(events.filter(e => e.wish_id === w.wish_id), new Date());
     console.log(`  - ${name}: status=${w.status}, recalled=${w.recalled}, applied=${w.applied}, verified=${w.verified}, 新鲜置信度=${conf}(P3 时间窗衰减)`);
 }
 console.log(`经验回流率基线 = ${verifiedWishes}/${recalledWishes} = ${refluxBaseline.toFixed(2)}(verified/recalled;单用户起步期样本稀疏属预期)`);
-if (pool.length === 0) console.log('(wish pool 为空——首访用户,指标从首条憧憬入池开始积累)');
-
-
-//# sourceURL=ts/scripts/memory-metrics.ts
+if (pool.length === 0)
+    console.log('(wish pool 为空——首访用户,指标从首条憧憬入池开始积累)');