create-principles-disciple 1.121.7 → 1.121.9

package/host-runtime/dist/product-telemetry/exporter.js

@@ -0,0 +1,71 @@
+/**
+ * Bounded asynchronous telemetry export client — Anonymous Product Telemetry
+ * v1 (PRI-599, SPEC §29-§34).
+ *
+ * One HTTPS POST per invocation, bounded by AbortController, never throwing.
+ * Failure mapping is coarse (SPEC §34): codes only, never messages, stacks,
+ * or response bodies. The injectable fetchFn keeps unit tests offline.
+ */
+export const DEFAULT_PRODUCT_TELEMETRY_ENDPOINT = 'https://principles-website.pages.dev/api/product-telemetry/snapshot';
+export const PRODUCT_TELEMETRY_TIMEOUT_MS = 8000;
+export const PRODUCT_TELEMETRY_MAX_BODY_BYTES = 4096;
+function defaultFetchFn(url, init) {
+    // fetch must be invoked against globalThis inside workers/gateway runtimes
+    // ("Illegal invocation" otherwise — same constraint as website relay-core).
+    return fetch.call(globalThis, url, init);
+}
+/**
+ * Export one snapshot. Never throws; every failure maps to a coarse code
+ * with a retryable hint the service uses for backoff.
+ */
+export async function exportSnapshot(args) {
+    const endpoint = args.endpoint ?? DEFAULT_PRODUCT_TELEMETRY_ENDPOINT;
+    const timeoutMs = args.timeoutMs ?? PRODUCT_TELEMETRY_TIMEOUT_MS;
+    const fetchFn = args.fetchFn ?? defaultFetchFn;
+    const body = JSON.stringify(args.snapshot);
+    if (Buffer.byteLength(body, 'utf8') > PRODUCT_TELEMETRY_MAX_BODY_BYTES) {
+        // Safety net: the strict schema keeps snapshots far below 4 KB; a
+        // violation here is a programmer error, never worth a network round trip.
+        return { ok: false, code: 'invalid_response', retryable: false };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchFn(endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body,
+            signal: controller.signal,
+        });
+        const { status } = response;
+        if (status >= 200 && status < 300) {
+            return { ok: true, status };
+        }
+        if (status === 400)
+            return { ok: false, code: 'http_400', retryable: false };
+        if (status === 429)
+            return { ok: false, code: 'http_429', retryable: true };
+        if (status >= 500)
+            return { ok: false, code: 'http_5xx', retryable: true };
+        return { ok: false, code: 'http_unexpected_status', retryable: false };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            return { ok: false, code: 'timeout', retryable: true };
+        }
+        // fetch rejects with TypeError on DNS failure / connection refused /
+        // TLS errors — indistinguishable at this boundary and equally retryable.
+        return { ok: false, code: 'network_error', retryable: true };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * First failure retries after 1h; any further failure within 24h backs off 6h.
+ * Combined with the service's dailyAttemptCount hard cap this bounds a bad day
+ * to at most 5 attempts (0h/1h/7h/13h/19h), independent of clock skew.
+ */
+export function nextRetryDelayMs(previousFailureWithin24h) {
+    return previousFailureWithin24h ? 6 * 60 * 60 * 1000 : 60 * 60 * 1000;
+}

package/host-runtime/dist/product-telemetry/milestone-readers.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Durable-fact milestone readers — Anonymous Product Telemetry v1
+ * (PRI-598, SPEC §21-§31; review remediation: tri-state facts).
+ *
+ * Read-only derivation of the six milestone facts from the authoritative
+ * durable sources verified in the Phase 0 authority matrix
+ * (docs/audit/anonymous-product-telemetry-feasibility.md §4):
+ *
+ *   initialized              <ws>/.pd/state.db schema_version populated
+ *   painObserved             <ws>/.state/trajectory.db pain_events EXISTS
+ *   principleObserved        principle tree ledger non-empty OR state.db principle_candidates EXISTS
+ *   activationObserved       state.db activations EXISTS
+ *   presenceReceiptObserved  state.db principle_applications level='presence' EXISTS
+ *   effectReceiptObserved    state.db principle_applications level='effect' EXISTS
+ *
+ * Readers never throw (telemetry must not break PD). Facts are TRI-STATE
+ * ("Unknown ≠ false"):
+ *
+ *   true   = source evaluable AND evidence observed
+ *   false  = source evaluable AND definitively no evidence (e.g. the DB file
+ *            does not exist at all — absence of any record IS the answer)
+ *   null   = source not currently evaluable (file exists but unreadable,
+ *            required table missing in an old schema, receipt collection
+ *            disabled) — recorded in local-only notes, never exported as
+ *            "observed false"
+ *
+ * Per-milestone evaluability (not all-or-nothing): each milestone consults
+ * only ITS authority/fallback sources; e.g. a malformed principle ledger
+ * does not make `initialized` unknown while state.db is readable.
+ * `principleObserved` combines its two evidence populations (pipeline
+ * candidates ∪ tree principles) with a three-valued OR: either source
+ * observing evidence yields true, false only when BOTH populations are
+ * definitively empty, and null whenever a population is unknown and the
+ * other did not observe evidence (Kleene OR — an evaluated-empty source
+ * can never resolve another source's unknown).
+ *
+ * `initializationFailed` can only be TRUE from an explicit readable-DB fact
+ * (state.db exists, opens, and its schema is definitively not initialized).
+ * An unreadable DB is an UNKNOWN, never a reported initialization failure —
+ * a read failure must not fabricate release-health signal.
+ *
+ * Receipt gating: when the `principle_receipt_ledger` flag is disabled, no
+ * receipt rows are being written, so absence of rows proves nothing — the
+ * receipt milestones render `null` (unavailable), not false.
+ *
+ * Every connection is closed before return (leaked handles would block
+ * Windows file cleanup and accumulate in the gateway process).
+ */
+import type { ProductTelemetryMilestoneInput, TelemetryFact } from '@principles/core/runtime-v2';
+export interface MilestoneFacts extends ProductTelemetryMilestoneInput {
+    initializationFailed: TelemetryFact;
+}
+export interface MilestoneReadResult {
+    facts: MilestoneFacts;
+    /** Local-only observability notes (never exported). */
+    notes: string[];
+}
+/**
+ * Derive milestone facts for one workspace. Never throws.
+ */
+export declare function readMilestoneFacts(workspaceDir: string): MilestoneReadResult;

package/host-runtime/dist/product-telemetry/milestone-readers.js

@@ -0,0 +1,234 @@
+/**
+ * Durable-fact milestone readers — Anonymous Product Telemetry v1
+ * (PRI-598, SPEC §21-§31; review remediation: tri-state facts).
+ *
+ * Read-only derivation of the six milestone facts from the authoritative
+ * durable sources verified in the Phase 0 authority matrix
+ * (docs/audit/anonymous-product-telemetry-feasibility.md §4):
+ *
+ *   initialized              <ws>/.pd/state.db schema_version populated
+ *   painObserved             <ws>/.state/trajectory.db pain_events EXISTS
+ *   principleObserved        principle tree ledger non-empty OR state.db principle_candidates EXISTS
+ *   activationObserved       state.db activations EXISTS
+ *   presenceReceiptObserved  state.db principle_applications level='presence' EXISTS
+ *   effectReceiptObserved    state.db principle_applications level='effect' EXISTS
+ *
+ * Readers never throw (telemetry must not break PD). Facts are TRI-STATE
+ * ("Unknown ≠ false"):
+ *
+ *   true   = source evaluable AND evidence observed
+ *   false  = source evaluable AND definitively no evidence (e.g. the DB file
+ *            does not exist at all — absence of any record IS the answer)
+ *   null   = source not currently evaluable (file exists but unreadable,
+ *            required table missing in an old schema, receipt collection
+ *            disabled) — recorded in local-only notes, never exported as
+ *            "observed false"
+ *
+ * Per-milestone evaluability (not all-or-nothing): each milestone consults
+ * only ITS authority/fallback sources; e.g. a malformed principle ledger
+ * does not make `initialized` unknown while state.db is readable.
+ * `principleObserved` combines its two evidence populations (pipeline
+ * candidates ∪ tree principles) with a three-valued OR: either source
+ * observing evidence yields true, false only when BOTH populations are
+ * definitively empty, and null whenever a population is unknown and the
+ * other did not observe evidence (Kleene OR — an evaluated-empty source
+ * can never resolve another source's unknown).
+ *
+ * `initializationFailed` can only be TRUE from an explicit readable-DB fact
+ * (state.db exists, opens, and its schema is definitively not initialized).
+ * An unreadable DB is an UNKNOWN, never a reported initialization failure —
+ * a read failure must not fabricate release-health signal.
+ *
+ * Receipt gating: when the `principle_receipt_ledger` flag is disabled, no
+ * receipt rows are being written, so absence of rows proves nothing — the
+ * receipt milestones render `null` (unavailable), not false.
+ *
+ * Every connection is closed before return (leaked handles would block
+ * Windows file cleanup and accumulate in the gateway process).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { loadLedger } from '@principles/core/principle-tree-ledger';
+import { loadFeatureFlagFromConfig } from '../pd-config.js';
+/** Feature flag whose absence of writes makes receipt absence unprovable. */
+const RECEIPT_LEDGER_FLAG = 'principle_receipt_ledger';
+/**
+ * Three-valued OR for the principle milestone's two evidence populations
+ * (pipeline candidates ∪ tree principles). `false` from one source means
+ * "its population is definitively empty" — it can never resolve the OTHER
+ * source's unknown, so any null keeps the existence claim unknown:
+ *   true OR anything  → true   (evidence observed somewhere)
+ *   false AND false    → false (both populations definitively empty)
+ *   otherwise          → null
+ * Review round 4: an authority-first variant that let a single definite
+ * `false` override a `null` silently degraded "unknown" into
+ * "observed false".
+ */
+function kleeneOr(a, b) {
+    if (a === true || b === true)
+        return true;
+    if (a === false && b === false)
+        return false;
+    return null;
+}
+/**
+ * Run EXISTS queries against one readonly DB. Opens, queries, closes —
+ * the connection never outlives the call. Per-query tri-state:
+ * a missing DB file is a DEFINITE false for every query (no record of any
+ * kind exists); an unreadable DB or a failing query (missing table in an
+ * older schema) is null — the source exists but cannot be evaluated.
+ */
+function existsQueries(dbPath, queries, context) {
+    const { notes, unavailableNote } = context;
+    const results = {};
+    try {
+        if (!fs.existsSync(dbPath)) {
+            for (const key of Object.keys(queries))
+                results[key] = false;
+            return results;
+        }
+    }
+    catch {
+        for (const key of Object.keys(queries))
+            results[key] = null;
+        notes.push(unavailableNote);
+        return results;
+    }
+    let db;
+    try {
+        db = new Database(dbPath, { readonly: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message.split('\n')[0] : String(error);
+        for (const key of Object.keys(queries))
+            results[key] = null;
+        notes.push(`${unavailableNote}: ${message}`);
+        return results;
+    }
+    try {
+        for (const [key, sql] of Object.entries(queries)) {
+            try {
+                results[key] = db.prepare(sql).pluck().get() === 1;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message.split('\n')[0] : String(error);
+                results[key] = null;
+                notes.push(`${unavailableNote}: ${message}`);
+            }
+        }
+    }
+    finally {
+        db.close();
+    }
+    return results;
+}
+/**
+ * Derive milestone facts for one workspace. Never throws.
+ */
+export function readMilestoneFacts(workspaceDir) {
+    const notes = [];
+    const facts = {
+        initialized: false,
+        painObserved: false,
+        principleObserved: false,
+        activationObserved: false,
+        presenceReceiptObserved: false,
+        effectReceiptObserved: false,
+        initializationFailed: false,
+    };
+    const workspace = path.resolve(workspaceDir);
+    const stateDbPath = path.join(workspace, '.pd', 'state.db');
+    // existsSync never throws (errors render as false) — safe inside the
+    // never-throws contract; the single lookup is shared by the note and the
+    // initializationFailed derivation below.
+    const stateDbExists = fs.existsSync(stateDbPath);
+    // The table-existence and populated checks are SEPARATE queries: a compound
+    // `EXISTS(sqlite_master…) AND EXISTS(schema_version)` errors out when the
+    // table is missing, which would erase the definitive "table absent" fact
+    // and render a readable DB unknown.
+    const stateResults = existsQueries(stateDbPath, {
+        schemaTableExists: "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name='schema_version')",
+        schemaVersionPopulated: 'SELECT EXISTS(SELECT 1 FROM schema_version)',
+        principleCandidates: 'SELECT EXISTS(SELECT 1 FROM principle_candidates)',
+        activations: 'SELECT EXISTS(SELECT 1 FROM activations)',
+        presenceReceipts: "SELECT EXISTS(SELECT 1 FROM principle_applications WHERE level='presence')",
+        effectReceipts: "SELECT EXISTS(SELECT 1 FROM principle_applications WHERE level='effect')",
+    }, { notes, unavailableNote: 'state_db_unreadable' });
+    if (!stateDbExists) {
+        // Distinct from unreadable: no DB at all means PD never ran here — a
+        // definite negative, not a degraded source.
+        notes.push('state_db_missing');
+    }
+    // noUncheckedIndexedAccess: a missing key would be a programmer error in
+    // the query table above; it degrades to null (unavailable), never false.
+    const schemaTableExists = stateResults.schemaTableExists ?? null;
+    const schemaVersionPopulated = stateResults.schemaVersionPopulated ?? null;
+    facts.initialized = schemaTableExists === null ? null : schemaTableExists === false ? false : schemaVersionPopulated ?? null;
+    // initializationFailed is claimable ONLY from a readable DB whose schema is
+    // DEFINITIVELY not initialized (explicit failure fact). A missing DB means
+    // PD was never brought up in this workspace (false); an unreadable or
+    // unevaluable schema query means we cannot know (null) — a read failure
+    // must never be recorded as an initialization failure.
+    facts.initializationFailed = !stateDbExists ? false : facts.initialized === null ? null : !facts.initialized;
+    facts.principleObserved = stateResults.principleCandidates ?? null;
+    facts.activationObserved = stateResults.activations ?? null;
+    // Receipt gating: with the ledger flag off, no receipt rows are written,
+    // so "no rows" is not evidence of "no receipts" — unavailable, not false.
+    const receiptFlag = loadFeatureFlagFromConfig(workspace, RECEIPT_LEDGER_FLAG);
+    if (!receiptFlag.enabled) {
+        facts.presenceReceiptObserved = null;
+        facts.effectReceiptObserved = null;
+        notes.push('receipt_collection_disabled');
+    }
+    else {
+        facts.presenceReceiptObserved = stateResults.presenceReceipts ?? null;
+        facts.effectReceiptObserved = stateResults.effectReceipts ?? null;
+    }
+    const trajectoryResults = existsQueries(path.join(workspace, '.state', 'trajectory.db'), { painEvents: 'SELECT EXISTS(SELECT 1 FROM pain_events)' }, { notes, unavailableNote: 'trajectory_db_unreadable' });
+    facts.painObserved = trajectoryResults.painEvents ?? null;
+    // Ledger fallback. loadLedger is fail-soft by contract (returns an empty
+    // tree for anything it cannot read), which would silently render a
+    // malformed ledger as "definitely no principles" — exactly the unknown→false
+    // collapse this remediation removes. Preflight the raw file so parse
+    // failures surface as null; loadLedger still owns the shape interpretation.
+    let ledgerFact = false;
+    const stateDir = path.join(workspace, '.state');
+    const ledgerPath = path.join(stateDir, 'principle_training_state.json');
+    const ledgerFilePresent = (() => {
+        try {
+            return fs.existsSync(ledgerPath);
+        }
+        catch {
+            return false;
+        }
+    })();
+    if (ledgerFilePresent) {
+        const preflightOk = (() => {
+            try {
+                JSON.parse(fs.readFileSync(ledgerPath, 'utf8'));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (!preflightOk) {
+            ledgerFact = null;
+            notes.push('principle_ledger_malformed');
+        }
+        else {
+            try {
+                const ledger = loadLedger(stateDir);
+                const principles = ledger?.tree?.principles;
+                ledgerFact = principles !== null && typeof principles === 'object' && Object.keys(principles).length > 0 ? true : false;
+            }
+            catch {
+                ledgerFact = null;
+                notes.push('principle_ledger_malformed');
+            }
+        }
+    }
+    facts.principleObserved = kleeneOr(facts.principleObserved, ledgerFact);
+    return { facts, notes };
+}

package/host-runtime/dist/product-telemetry/service.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Product telemetry service — Anonymous Product Telemetry v1
+ * (PRI-597/598/599 orchestration; review remediation: workspace unit).
+ *
+ * Single seam for the CLI control plane (`pd telemetry status/enable/disable/
+ * preview/reset`) and the two fire-and-forget export triggers (OpenClaw plugin
+ * workspace init, pd-console startup). Export requires ALL gates:
+ *
+ *   canExport = feature flag anonymous_product_telemetry (workspace config)
+ *             AND consent granted (~/.pd/product-telemetry.json)
+ *             AND environment not suppressed (eligibility.ts)
+ *
+ * Scope model (review remediation P1-1): the MEASUREMENT UNIT is the
+ * workspace. Consent, consentVersion, and the telemetry secret are
+ * machine-scope; the daily identity, dedup, retry bookkeeping, and export
+ * lock are workspace-scope. One workspace's success/backoff/lock never
+ * suppresses another workspace on the same installation.
+ */
+import { type ProductTelemetrySnapshotV1 } from '@principles/core/runtime-v2';
+import { type ProductTelemetryConsent } from './consent-store.js';
+import { type TelemetrySuppressionReason } from './eligibility.js';
+import { type TelemetryFetchFn } from './exporter.js';
+export declare const ANONYMOUS_PRODUCT_TELEMETRY_FLAG = "anonymous_product_telemetry";
+export declare const PD_TELEMETRY_DISABLED_ENV = "PD_TELEMETRY_DISABLED";
+export declare const PREVIEW_BANNER = "Preview only. Nothing was sent.";
+/** Hard cap on export attempts per UTC day per workspace (1 initial + 4 retries; review round 2). */
+export declare const MAX_DAILY_EXPORT_ATTEMPTS = 5;
+export interface ProductTelemetryServiceDeps {
+    /** Installation home dir. Default os.homedir(). */
+    homeDir?: string;
+    /** Environment snapshot. Default process.env (injected in tests). */
+    env?: Record<string, string | undefined>;
+    /** Executing module dir for repo-checkout detection. Default this file's dir. */
+    moduleDir?: string;
+    fetchFn?: TelemetryFetchFn;
+    endpoint?: string;
+    now?: () => number;
+    logger?: {
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+    };
+}
+export interface TelemetryGates {
+    flagEnabled: boolean | null;
+    flagSource: string | null;
+    consent: ProductTelemetryConsent;
+    environmentSuppressed: boolean;
+    suppressionReasons: TelemetrySuppressionReason[];
+    /** All gates open right now (for the resolved workspace). */
+    canExport: boolean;
+    blockers: string[];
+}
+export interface ProductTelemetryStatusView extends TelemetryGates {
+    consentVersion: string;
+    hasSecret: boolean;
+    lastAttemptedAt?: string;
+    lastSucceededAt?: string;
+    lastFailureCode?: string;
+    nextRetryAt?: string;
+    endpoint: string;
+    nextAction?: string;
+}
+export interface ProductTelemetryPreview {
+    banner: typeof PREVIEW_BANNER;
+    snapshot: ProductTelemetrySnapshotV1;
+    gates: TelemetryGates;
+    /** Local-only reader notes (source degraded reasons) — never exported. */
+    notes: string[];
+    /** True when no stored secret exists yet and an ephemeral one was derived for display. */
+    secretEphemeral: boolean;
+}
+export type MaybeExportOutcome = {
+    attempted: true;
+    ok: boolean;
+    httpStatus?: number;
+    failureCode?: string;
+} | {
+    attempted: false;
+    skipReason: string;
+};
+export declare function createProductTelemetryService(deps?: ProductTelemetryServiceDeps): {
+    /** Status for `pd telemetry status`. Never exposes the secret. */
+    getStatus(workspaceDir?: string): {
+        ok: true;
+        view: ProductTelemetryStatusView;
+    } | {
+        ok: false;
+        reason: string;
+        nextAction: string;
+    };
+    /** Exact outbound payload for `pd telemetry preview`. Never sends. */
+    preview(workspaceDir: string): ProductTelemetryPreview;
+    /** `pd telemetry enable --confirm`: explicit granted consent (+ secret). */
+    enable(): {
+        ok: true;
+        consent: 'granted';
+    } | {
+        ok: false;
+        reason: string;
+        nextAction: string;
+    };
+    /** `pd telemetry disable --confirm`: deny consent and delete export identity. */
+    disable(): {
+        ok: true;
+        consent: 'denied';
+    } | {
+        ok: false;
+        reason: string;
+        nextAction: string;
+    };
+    /** `pd telemetry reset --confirm`: delete identity; fresh secret only if still enabled. */
+    reset(): {
+        ok: true;
+        consent: ProductTelemetryConsent;
+    } | {
+        ok: false;
+        reason: string;
+        nextAction: string;
+    };
+    /**
+     * One gate-checked export attempt for a normal-activity trigger.
+     * Never throws; every path returns a structured outcome.
+     *
+     * Concurrency: a per-workspace lock file
+     * (`product-telemetry.json.export-lock.<scopeId>`) closes the read→send→
+     * write race between simultaneous triggers (OpenClaw gateway init +
+     * pd-console startup in different processes) WITHOUT coupling unrelated
+     * workspaces. Stale locks (crashed holder) are taken over after
+     * EXPORT_LOCK_STALE_MS.
+     */
+    maybeExportDaily(workspaceDir: string): Promise<MaybeExportOutcome>;
+};
+export type ProductTelemetryService = ReturnType<typeof createProductTelemetryService>;
+/**
+ * Fire-and-forget scheduling for normal-activity triggers. The timer is
+ * unref'd so it never keeps a host process alive, and every failure path is
+ * contained — telemetry can never block or crash PD startup or hooks.
+ */
+export declare function scheduleProductTelemetryExport(service: ProductTelemetryService, workspaceDir: string, scheduleLogger?: {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+}): void;