@danceiny/gotry 0.2.0-rc.27 → 0.2.0-rc.28

package/dist/scripts/m3-cohort.js

@@ -0,0 +1,310 @@
+#!/usr/bin/env tsx
+/**
+ * Explicit opt-in M3 seed-cohort capture CLI (issue #22).
+ *
+ * Produces the records `scripts/product-metrics.ts` consumes. The scorer is the only
+ * component that divides anything; this CLI only records funnel facts and then hands the
+ * written evidence root straight back to the scorer for verification.
+ *
+ * The production CLI intentionally has no `--at` flag: timestamps come from the local
+ * clock. Tests inject clocks through `../src/m3-cohort.ts`.
+ *
+ * HMAC key custody: `GOTRY_M3_COHORT_HMAC_KEY` (>= 32 chars) lives outside the repository
+ * and is never printed by this CLI. Losing it makes the store unreadable by design, and
+ * `verify` needs it too — the export attestation is keyed, not a public digest.
+ *
+ * Argv exposure (accepted, documented): `--participant`, `--plan` and `--consent` carry raw
+ * labels on the command line, so they are visible to `ps` and land in shell history. Only
+ * their HMAC refs are ever persisted, but the invocation itself is not secret. For a real
+ * cohort, drive this CLI from a script whose history is not shared, or export the labels
+ * from a file the shell does not record; never pass anything you would not put in `ps`.
+ *
+ *   npx tsx scripts/m3-cohort.ts init --state-root "$ROOT" --consent "$C" \
+ *     --cohort m3-seed --evidence-kind real_seed_cohort \
+ *     --window-start 2026-10-01T00:00:00.000Z --window-end 2026-12-31T23:59:59.000Z \
+ *     --timezone Asia/Shanghai --attribution gotry_primary
+ *   npx tsx scripts/m3-cohort.ts enroll   ... --participant <handle> --invited --participant-consent
+ *   npx tsx scripts/m3-cohort.ts deliver  ... --participant <handle> --plan <handle> --attribution gotry_primary
+ *   npx tsx scripts/m3-cohort.ts finalize ... --participant <handle> --plan <handle>
+ *   npx tsx scripts/m3-cohort.ts nps      ... --participant <handle> --plan <handle> --score 9
+ *   npx tsx scripts/m3-cohort.ts poi-lock ... --participant <handle> --plan <handle> --locked-claims 12 --invalid-claims 0
+ *   npx tsx scripts/m3-cohort.ts export   ... --evidence-root <dir>
+ *   npx tsx scripts/m3-cohort.ts verify   --evidence-root <dir>        # needs the HMAC key
+ *   npx tsx scripts/m3-cohort.ts lock-status --state-root "$ROOT"      # read-only
+ *   npx tsx scripts/m3-cohort.ts unlock     --state-root "$ROOT"       # dead writer only
+ */
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { enrollParticipant, exportM3Cohort, initM3Cohort, inspectStoreLock, M3CohortError, M3_SIMULATION_PROVENANCE_SCHEMA, recordNps, recordPlanDelivered, recordPlanFinalized, recordPoiLock, unlockStore, verifyExportedEvidence, } from '../src/m3-cohort.js';
+import { parseCohortRecord, parseManifest, scoreProductMetrics } from './product-metrics.js';
+const ERROR_CODES = [
+    'bad_args',
+    'cohort_already_initialized',
+    'cohort_consent_mismatch',
+    'cohort_key_mismatch',
+    'cohort_not_initialized',
+    'evidence_kind_mismatch',
+    'evidence_root_conflict',
+    'export_validation_failed',
+    'internal_error',
+    'invalid_hmac_key',
+    'invalid_input',
+    'invalid_store',
+    'invalid_transition',
+    'lock_busy',
+    'missing_consent',
+    'missing_hmac_key',
+    'missing_state_root',
+    'output_exists',
+    'simulation_forbidden_in_real_cohort',
+    'simulation_label_required',
+    'unsafe_state_root',
+];
+function parseFlags(args) {
+    const [command, ...rest] = args;
+    if (!command)
+        throw new M3CohortError('bad_args');
+    const flags = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const token = rest[index];
+        if (!token.startsWith('--'))
+            throw new M3CohortError('bad_args');
+        const key = token.slice(2);
+        if (!key)
+            throw new M3CohortError('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 M3CohortError('bad_args');
+    if (value === undefined && required)
+        throw new M3CohortError(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 M3CohortError('bad_args');
+    const list = Array.isArray(value) ? value : [value];
+    return list.map(item => {
+        if (item === true)
+            throw new M3CohortError('bad_args');
+        return item;
+    });
+}
+function boolFlag(flags, key) {
+    const value = flags[key];
+    if (value === undefined)
+        return false;
+    if (value !== true)
+        throw new M3CohortError('bad_args');
+    return true;
+}
+function exclusiveBool(flags, trueKey, falseKey) {
+    const positive = boolFlag(flags, trueKey);
+    const negative = boolFlag(flags, falseKey);
+    if (positive === negative)
+        throw new M3CohortError('invalid_input');
+    return positive;
+}
+function integerFlag(flags, key) {
+    const raw = one(flags, key);
+    if (!/^\d{1,9}$/.test(raw))
+        throw new M3CohortError('invalid_input');
+    return Number(raw);
+}
+function common(flags) {
+    const stateRoot = one(flags, 'state-root');
+    const consent = one(flags, 'consent', false);
+    if (!consent)
+        throw new M3CohortError('missing_consent');
+    return { stateRoot: stateRoot, consent, hmacKey: process.env['GOTRY_M3_COHORT_HMAC_KEY'] };
+}
+function ensureNoUnknownFlags(flags, allowed) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(flags)) {
+        if (!allowedSet.has(key))
+            throw new M3CohortError('bad_args');
+    }
+}
+function attributionFlag(flags) {
+    const value = one(flags, 'attribution');
+    if (value !== 'gotry_primary' && value !== 'gotry_assisted')
+        throw new M3CohortError('invalid_input');
+    return value;
+}
+function attributionList(flags) {
+    const values = many(flags, 'attribution');
+    if (values.length === 0)
+        throw new M3CohortError('invalid_input');
+    return values.map(value => {
+        if (value !== 'gotry_primary' && value !== 'gotry_assisted')
+            throw new M3CohortError('invalid_input');
+        return value;
+    });
+}
+function simulationFlags(flags) {
+    const simulated = boolFlag(flags, 'simulated');
+    const personaId = one(flags, 'persona-id', false);
+    const productModel = one(flags, 'product-model', false);
+    const personaModel = one(flags, 'persona-model', false);
+    const promptDigest = one(flags, 'prompt-digest', false);
+    const provided = [personaId, productModel, personaModel, promptDigest];
+    if (!simulated) {
+        if (provided.some(value => value !== undefined))
+            throw new M3CohortError('invalid_input');
+        return undefined;
+    }
+    if (provided.some(value => value === undefined))
+        throw new M3CohortError('invalid_input');
+    return {
+        schema_version: M3_SIMULATION_PROVENANCE_SCHEMA,
+        kind: 'llm_persona',
+        persona_id: personaId,
+        product_model: productModel,
+        persona_model: personaModel,
+        prompt_digest: promptDigest,
+    };
+}
+function output(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+/** Consumer-side verification: the exact parsers and scorer the M3 gate uses. */
+export function scorerValidator(payload) {
+    const manifest = parseManifest(JSON.parse(JSON.stringify(payload.manifest)));
+    const cohort = payload.cohort.map((record, index) => parseCohortRecord(JSON.parse(JSON.stringify(record)), index));
+    const summary = scoreProductMetrics(manifest, cohort, []);
+    if (manifest.evidence_kind === 'synthetic_fixture' && summary.business_pass) {
+        throw new M3CohortError('export_validation_failed');
+    }
+}
+function run(command, flags) {
+    switch (command) {
+        case 'init': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'cohort', 'evidence-kind', 'window-start', 'window-end', 'timezone', 'attribution']);
+            const evidenceKind = one(flags, 'evidence-kind');
+            if (evidenceKind !== 'real_seed_cohort' && evidenceKind !== 'synthetic_fixture')
+                throw new M3CohortError('invalid_input');
+            output(initM3Cohort({
+                ...common(flags),
+                cohort: one(flags, 'cohort'),
+                evidenceKind,
+                windowStartAt: one(flags, 'window-start'),
+                windowEndAt: one(flags, 'window-end'),
+                timezone: one(flags, 'timezone'),
+                allowedAttribution: attributionList(flags),
+            }));
+            return;
+        }
+        case 'enroll': {
+            ensureNoUnknownFlags(flags, [
+                'state-root', 'consent', 'participant', 'invited', 'not-invited', 'participant-consent',
+                'participant-consent-withdrawn', 'test-or-staff', 'simulated', 'persona-id', 'product-model',
+                'persona-model', 'prompt-digest',
+            ]);
+            output(enrollParticipant({
+                ...common(flags),
+                participant: one(flags, 'participant'),
+                invited: exclusiveBool(flags, 'invited', 'not-invited'),
+                participantConsent: exclusiveBool(flags, 'participant-consent', 'participant-consent-withdrawn'),
+                testOrStaff: boolFlag(flags, 'test-or-staff'),
+                simulation: simulationFlags(flags),
+            }));
+            return;
+        }
+        case 'deliver': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'participant', 'plan', 'attribution']);
+            output(recordPlanDelivered({
+                ...common(flags),
+                participant: one(flags, 'participant'),
+                plan: one(flags, 'plan'),
+                attribution: attributionFlag(flags),
+            }));
+            return;
+        }
+        case 'finalize': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'participant', 'plan']);
+            output(recordPlanFinalized({ ...common(flags), participant: one(flags, 'participant'), plan: one(flags, 'plan') }));
+            return;
+        }
+        case 'nps': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'participant', 'plan', 'score']);
+            output(recordNps({
+                ...common(flags),
+                participant: one(flags, 'participant'),
+                plan: one(flags, 'plan'),
+                score: integerFlag(flags, 'score'),
+            }));
+            return;
+        }
+        case 'poi-lock': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'participant', 'plan', 'locked-claims', 'invalid-claims']);
+            output(recordPoiLock({
+                ...common(flags),
+                participant: one(flags, 'participant'),
+                plan: one(flags, 'plan'),
+                lockedClaims: integerFlag(flags, 'locked-claims'),
+                invalidClaims: integerFlag(flags, 'invalid-claims'),
+            }));
+            return;
+        }
+        case 'export': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'evidence-root']);
+            const evidenceRoot = one(flags, 'evidence-root');
+            const shared = common(flags);
+            const { payload, result } = exportM3Cohort({ ...shared, evidenceRoot, validate: scorerValidator });
+            // Verify the bytes that actually landed: re-read the evidence root through the real
+            // scorer parsers plus the keyed attestation check.
+            const manifest = parseManifest(JSON.parse(JSON.stringify(payload.manifest)));
+            const cohort = payload.cohort.map((record, index) => parseCohortRecord(JSON.parse(JSON.stringify(record)), index));
+            const summary = scoreProductMetrics(manifest, cohort, []);
+            const verification = verifyExportedEvidence(evidenceRoot, shared.hmacKey);
+            output({ ...result, verification, scorer_summary: summary });
+            return;
+        }
+        case 'verify': {
+            ensureNoUnknownFlags(flags, ['evidence-root']);
+            output(verifyExportedEvidence(one(flags, 'evidence-root'), process.env['GOTRY_M3_COHORT_HMAC_KEY']));
+            return;
+        }
+        case 'lock-status': {
+            ensureNoUnknownFlags(flags, ['state-root']);
+            output(inspectStoreLock(one(flags, 'state-root')));
+            return;
+        }
+        case 'unlock': {
+            ensureNoUnknownFlags(flags, ['state-root']);
+            output(unlockStore(one(flags, 'state-root')));
+            return;
+        }
+        default:
+            throw new M3CohortError('bad_args');
+    }
+}
+function main() {
+    try {
+        const { command, flags } = parseFlags(process.argv.slice(2));
+        run(command, flags);
+    }
+    catch (error) {
+        const code = error instanceof M3CohortError && ERROR_CODES.includes(error.code) ? error.code : 'internal_error';
+        process.stderr.write(`m3_cohort_error:${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/nightly-evidence-tests.js

@@ -4,7 +4,9 @@
  *   - 封存价表仅可审计换算(peak 保守上界),未知模型 fail-closed,usage 缺失 fail-closed;
  *   - run_key 确定性 + 记录必须过消费方 parseNightlyRun(生产器写的就是评分器读的);
  *   - 无凭证 = waiting_external_evidence,不写任何文件(issue #22 停机纪律);
- *   - --dry-run mock 全链演练可跑通且绝不落盘。
+ *   - --dry-run mock 全链演练可跑通且绝不落盘;
+ *   - --dry-run 默认离线(issue #617):PATH 上的计数 fake hbcli 零次被调起(第三轮「我订了酒店:…」会触发 PoI 探针),
+ *     operator 显式设置的 GOTRY_HBCLI_LIVE 不被覆盖(同时是 fake 可达的 positive control),演练后环境原样还原。
  * 真跑(花钱)不在 CI:heartbeat/founder 手动 `npx tsx scripts/nightly-evidence.ts`。
  *
  * 价表 schema 演进(issue #49):v1 (legacy DeepSeek only) / v2 (provider-aware;DeepSeek+MiniMax);
@@ -13,7 +15,7 @@
  *   usage 缺失 fail-closed、run_key 确定性 + 消费方 parseNightlyRun、无凭证 waiting、dry-run 零落盘。
  */
 import assert from 'node:assert/strict';
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { buildNightlyRunRecord, loadPriceTable, loadPromptSet, priceRunCost, runNightlyEvidence, } from './nightly-evidence.js';
@@ -158,4 +160,44 @@ finally {
     rmSync(dryParent, { recursive: true, force: true });
 }
 ok('dry-run mock 全链演练 + real_llm=false + 零落盘');
+// ---- 7b. issue #617:dry-run 是离线「mock 全链演练」,不得经 runTurn→probePoi→anythingSearch 连真实 hbcli 后端 ----
+// 受控 PATH 上放计数 fake(只用 shell 内建);HOME 指向空目录,已知安装位回退碰不到开发机真实 hbcli。
+const hbcliProbeRoot = mkdtempSync(join(tmpdir(), 'nightly-hbcli-'));
+const hbcliProbeBin = join(hbcliProbeRoot, 'bin');
+const hbcliCallsLog = join(hbcliProbeRoot, 'calls.log');
+mkdirSync(hbcliProbeBin);
+mkdirSync(join(hbcliProbeRoot, 'home'));
+writeFileSync(join(hbcliProbeBin, 'hbcli'), `#!/bin/sh\nprintf 'call\\n' >> '${hbcliCallsLog}'\nprintf '%s' '{"candidates":[]}'\n`, { mode: 0o755 });
+const hbcliCalls = () => existsSync(hbcliCallsLog) ? readFileSync(hbcliCallsLog, 'utf8').split('\n').filter(Boolean).length : 0;
+const savedEnv = { PATH: process.env['PATH'], HOME: process.env['HOME'], LIVE: process.env['GOTRY_HBCLI_LIVE'] };
+const restoreEnv = (key, value) => {
+    if (value === undefined)
+        delete process.env[key];
+    else
+        process.env[key] = value;
+};
+try {
+    process.env['PATH'] = `${hbcliProbeBin}:${savedEnv.PATH ?? ''}`;
+    process.env['HOME'] = join(hbcliProbeRoot, 'home');
+    const dryRoot2 = join(hbcliProbeRoot, 'evidence');
+    // 缺省(operator 未设):演练期间 GOTRY_HBCLI_LIVE=0,fake 零次被调起,演练后环境原样还原(无泄漏)
+    delete process.env['GOTRY_HBCLI_LIVE'];
+    const offlineDry = await runNightlyEvidence({ evidenceRoot: dryRoot2, dryRun: true, clock: () => new Date(executeAt) });
+    assert.equal(offlineDry.state, 'dry_run');
+    assert.equal(hbcliCalls(), 0, 'dry-run 缺省离线:PATH 上的 fake hbcli 必须被调起 0 次');
+    assert.equal(process.env['GOTRY_HBCLI_LIVE'], undefined, 'dry-run 结束后必须还原 GOTRY_HBCLI_LIVE(不得泄漏进后续进程内套件)');
+    // operator 显式设置的值不被覆盖——同时是 positive control:证明上面的「零次」不是因为 fake 不可达
+    process.env['GOTRY_HBCLI_LIVE'] = '1';
+    const explicitDry = await runNightlyEvidence({ evidenceRoot: dryRoot2, dryRun: true, clock: () => new Date(executeAt) });
+    assert.equal(explicitDry.state, 'dry_run');
+    assert.ok(hbcliCalls() >= 1, `显式 GOTRY_HBCLI_LIVE=1 不得被 dry-run 覆盖,PoI 探针应调起 fake(实际 ${hbcliCalls()} 次)`);
+    assert.equal(process.env['GOTRY_HBCLI_LIVE'], '1', '显式值演练后原样保留');
+}
+finally {
+    restoreEnv('PATH', savedEnv.PATH);
+    restoreEnv('HOME', savedEnv.HOME);
+    restoreEnv('GOTRY_HBCLI_LIVE', savedEnv.LIVE);
+    rmSync(hbcliProbeRoot, { recursive: true, force: true });
+}
+ok('dry-run 缺省 GOTRY_HBCLI_LIVE=0:fake hbcli 零次调起 + 环境还原;显式值不覆盖(positive control)');
 console.log(`nightly-evidence tests: ${passed} 组断言全绿(offline,真跑不在 CI)`);

package/dist/scripts/nightly-evidence.js

@@ -6,7 +6,7 @@
  *
  * 运行(在 ts/ 下):
  *   npx tsx scripts/nightly-evidence.ts                  # 真跑:需 LLM_API_KEY,追加证据记录
- *   npx tsx scripts/nightly-evidence.ts --dry-run        # mock 全链演练,绝不写证据
+ *   npx tsx scripts/nightly-evidence.ts --dry-run        # mock 全链演练,绝不写证据(缺省 GOTRY_HBCLI_LIVE=0:不连真实 hbcli;显式设置则尊重)
  *   npx tsx scripts/nightly-evidence.ts --format json    # 机器可读状态(heartbeat 消费)
  *   npx tsx scripts/nightly-evidence.ts --no-env-file    # 不读仓根 .env(等待态测试用)
  *
@@ -190,6 +190,17 @@ function arg(name) {
     const index = process.argv.indexOf(name);
     return index >= 0 ? process.argv[index + 1] : undefined;
 }
+/**
+ * issue #617:`--dry-run` 是离线「mock 全链演练」,但 runTurn 的 PoI 探针会 spawn 本机真实 hbcli
+ * (带凭据即连真实后端、耗配额)。演练期间把离线开关缺省置 0——operator 显式设过 GOTRY_HBCLI_LIVE
+ * (含空串)则一律不覆盖;返回还原函数(本函数在进程内被测试与 persona harness 复用,不得泄漏环境)。
+ */
+function defaultHbcliLiveOff() {
+    if (process.env['GOTRY_HBCLI_LIVE'] !== undefined)
+        return () => { };
+    process.env['GOTRY_HBCLI_LIVE'] = '0';
+    return () => { delete process.env['GOTRY_HBCLI_LIVE']; };
+}
 export async function runNightlyEvidence(options) {
     const clock = options.clock ?? (() => new Date());
     const llmKey = process.env['LLM_API_KEY'] ?? process.env['DEEPSEEK_API_KEY'];
@@ -203,9 +214,15 @@ export async function runNightlyEvidence(options) {
     const port = options.dryRun ? createMockLlm(packPath) : createOpenAICompatLlm(packPath);
     const state = newState();
     const history = [];
-    for (const turn of promptSet.turns) {
-        const { reply } = await runTurn(state, turn, port, [...history], solvePort);
-        history.push({ role: 'user', text: turn }, { role: 'assistant', text: reply });
+    const restoreHbcliLive = options.dryRun ? defaultHbcliLiveOff() : () => { };
+    try {
+        for (const turn of promptSet.turns) {
+            const { reply } = await runTurn(state, turn, port, [...history], solvePort);
+            history.push({ role: 'user', text: turn }, { role: 'assistant', text: reply });
+        }
+    }
+    finally {
+        restoreHbcliLive();
     }
     const promptSetSha = sha256Of(promptSet);
     // history 是 user/assistant 交错序列;assistant 回复落在每个 user 之后(index*2+1)