@principles/host-runtime 0.1.0 → 0.2.0

package/dist/product-telemetry/consent-store.js

@@ -0,0 +1,329 @@
+/**
+ * Product telemetry control-state store — Anonymous Product Telemetry v1
+ * (PRI-597, SPEC §44; review remediation: workspace-scoped export state).
+ *
+ * Persists the telemetry control state to `~/.pd/product-telemetry.json`.
+ * This file is Telemetry Control State — it never enters
+ * Principle/Pain/receipt/governance stores, and the secret never leaves the
+ * machine.
+ *
+ * Scope model (schema v2, review remediation P1-1):
+ * - MACHINE scope: consent, consentVersion, telemetrySecret.
+ * - WORKSPACE scope: `workspaceExports[scopeId]` — per-workspace dedup,
+ *   retry, and attempt bookkeeping keyed by the opaque local scope ID
+ *   (HMAC(secret, canonical workspace path); never uploaded). One
+ *   workspace succeeding must never suppress another workspace's export.
+ *
+ * Migration from schema v1: consent, consentVersion, and telemetrySecret are
+ * preserved; legacy machine-global export bookkeeping (lastSucceededAt,
+ * retry state, attempt counters) is DISCARDED — it cannot be attributed to a
+ * workspace, and it is operational state, not a governance fact. Dropping it
+ * can cause at most one extra same-day snapshot per installation.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { generateTelemetrySecretHex, isValidBucketDate, isValidTelemetrySecretHex, PRODUCT_TELEMETRY_CONSENT_VERSION, } from '@principles/core/runtime-v2';
+export const PRODUCT_TELEMETRY_STATE_FILENAME = 'product-telemetry.json';
+export const PRODUCT_TELEMETRY_CONTROL_SCHEMA_VERSION = '2';
+/** v1 files are still read (then migrated in memory and rewritten as v2). */
+export const PRODUCT_TELEMETRY_LEGACY_CONTROL_SCHEMA_VERSION = '1';
+/** Hard bound on tracked workspaces so the file cannot grow unboundedly. */
+export const MAX_WORKSPACE_EXPORT_ENTRIES = 200;
+/**
+ * Entries untouched for this long are pruned on the next write. This is local
+ * telemetry operational state only — no workspace history is retained.
+ */
+export const WORKSPACE_EXPORT_STATE_MAX_AGE_DAYS = 30;
+export function defaultProductTelemetryControlState() {
+    return { consent: 'unset', consentVersion: PRODUCT_TELEMETRY_CONSENT_VERSION, schemaVersion: PRODUCT_TELEMETRY_CONTROL_SCHEMA_VERSION };
+}
+export function getProductTelemetryStatePath(homeDir) {
+    return path.join(path.resolve(homeDir), '.pd', PRODUCT_TELEMETRY_STATE_FILENAME);
+}
+function isConsent(value) {
+    return value === 'unset' || value === 'granted' || value === 'denied';
+}
+/**
+ * Optional timestamp fields must be parseable dates, not just short strings —
+ * a "garbage" lastSucceededAt/nextRetryAt would otherwise slip validation and
+ * turn into NaN inside Date.parse, silently skipping same-day dedup or retry
+ * backoff (fail-loud contract, review round 2).
+ */
+function isOptionalIsoString(value) {
+    if (value === undefined)
+        return true;
+    if (typeof value !== 'string' || value.length === 0 || value.length > 40)
+        return false;
+    return !Number.isNaN(Date.parse(value));
+}
+function isOptionalAttemptBucketDate(value) {
+    if (value === undefined)
+        return true;
+    return isValidBucketDate(value);
+}
+function isOptionalAttemptCount(value) {
+    return value === undefined || (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 99);
+}
+function isOptionalFailureCode(value) {
+    return value === undefined || (typeof value === 'string' && value.length > 0 && value.length <= 40);
+}
+function isScopeKey(value) {
+    return typeof value === 'string' && /^[0-9a-f]{4,32}$/.test(value);
+}
+/** Validate one `workspaceExports` entry; collect errors under `prefix`. */
+function workspaceExportErrors(entry, prefix) {
+    const errors = [];
+    for (const key of Object.keys(entry)) {
+        if (!['lastAttemptedAt', 'lastSucceededAt', 'lastFailureCode', 'nextRetryAt', 'dailyAttemptCount', 'attemptBucketDate'].includes(key)) {
+            errors.push(`${prefix}: unknown field '${key}'`);
+        }
+    }
+    if (!isOptionalIsoString(entry.lastAttemptedAt) || !isOptionalIsoString(entry.lastSucceededAt) || !isOptionalIsoString(entry.nextRetryAt)) {
+        errors.push(`${prefix}: timestamps must be parseable ISO-8601 strings (≤40 chars) when present`);
+    }
+    if (!isOptionalAttemptCount(entry.dailyAttemptCount))
+        errors.push(`${prefix}: dailyAttemptCount must be an integer 0–99 when present`);
+    if (!isOptionalAttemptBucketDate(entry.attemptBucketDate))
+        errors.push(`${prefix}: attemptBucketDate must be a valid YYYY-MM-DD UTC date when present`);
+    if (!isOptionalFailureCode(entry.lastFailureCode))
+        errors.push(`${prefix}: lastFailureCode must be a short non-empty string when present`);
+    return errors;
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Read and validate the control state. A missing file is the normal
+ * never-configured case (defaults, existed=false). A malformed file is a
+ * loud failure — silently treating it as "unset" could re-prompt or re-export
+ * against the user's recorded decision (rc-3/rc-9).
+ *
+ * v1 files are migrated in memory (export bookkeeping dropped, consent
+ * identity preserved); the migration is persisted on the next write.
+ */
+export function readProductTelemetryControlState(homeDir) {
+    const filePath = getProductTelemetryStatePath(homeDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        // Guarded code access (rc-1/rc-2: runtime check before use; rc-5:
+        // Object.hasOwn on untrusted objects; no NodeJS namespace in this config).
+        const codeValue = typeof error === 'object' && error !== null && Object.hasOwn(error, 'code')
+            ? error.code
+            : undefined;
+        const code = typeof codeValue === 'string' ? codeValue : undefined;
+        if (code === 'ENOENT') {
+            return { ok: true, state: defaultProductTelemetryControlState(), existed: false };
+        }
+        return {
+            ok: false,
+            reason: `product_telemetry_state_unreadable: ${code ?? String(error)}`,
+            nextAction: `Check permissions on ${filePath}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'product_telemetry_state_malformed_json',
+            nextAction: `Fix or delete ${filePath} (delete = consent returns to unset)`,
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            reason: 'product_telemetry_state_malformed_shape',
+            nextAction: `Fix or delete ${filePath} (delete = consent returns to unset)`,
+        };
+    }
+    const obj = parsed;
+    const { schemaVersion } = obj;
+    const isV1 = schemaVersion === PRODUCT_TELEMETRY_LEGACY_CONTROL_SCHEMA_VERSION;
+    const isV2 = schemaVersion === PRODUCT_TELEMETRY_CONTROL_SCHEMA_VERSION;
+    if (!isV1 && !isV2) {
+        return {
+            ok: false,
+            reason: `product_telemetry_state_malformed: schemaVersion must be '${PRODUCT_TELEMETRY_CONTROL_SCHEMA_VERSION}' or legacy '${PRODUCT_TELEMETRY_LEGACY_CONTROL_SCHEMA_VERSION}'`,
+            nextAction: `Fix or delete ${filePath} (delete = consent returns to unset)`,
+        };
+    }
+    // v1 machine-global export fields exist only in v1 files; v2 files carry
+    // workspaceExports instead. Unknown keys are rejected per shape.
+    const allowedKeys = isV1
+        ? ['consent', 'consentVersion', 'telemetrySecret', 'lastAttemptedAt', 'lastSucceededAt', 'lastFailureCode', 'nextRetryAt', 'dailyAttemptCount', 'attemptBucketDate', 'schemaVersion']
+        : ['consent', 'consentVersion', 'telemetrySecret', 'workspaceExports', 'schemaVersion'];
+    const errors = [];
+    for (const key of Object.keys(obj)) {
+        if (!allowedKeys.includes(key)) {
+            errors.push(`unknown field '${key}'`);
+        }
+    }
+    if (!isConsent(obj.consent))
+        errors.push('consent must be unset|granted|denied');
+    if (typeof obj.consentVersion !== 'string' || obj.consentVersion.length === 0 || obj.consentVersion.length > 8)
+        errors.push('consentVersion must be a short non-empty string');
+    if (!isValidTelemetrySecretHex(obj.telemetrySecret) && obj.telemetrySecret !== undefined)
+        errors.push('telemetrySecret must be 64 hex chars when present');
+    if (isV1) {
+        // v1 legacy export fields are migrated by DISCARDING them — validating
+        // values that are about to be dropped would only turn a smooth migration
+        // into a hard failure (the identity fields carry the user's decision).
+        // Only the field-NAME allowlist above still applies to v1 files.
+    }
+    else {
+        if (obj.workspaceExports !== undefined) {
+            if (typeof obj.workspaceExports !== 'object' || obj.workspaceExports === null || Array.isArray(obj.workspaceExports)) {
+                errors.push('workspaceExports must be an object');
+            }
+            else {
+                const entries = obj.workspaceExports;
+                const scopeKeys = Object.keys(entries);
+                if (scopeKeys.length > MAX_WORKSPACE_EXPORT_ENTRIES) {
+                    errors.push(`workspaceExports must track at most ${MAX_WORKSPACE_EXPORT_ENTRIES} workspaces`);
+                }
+                for (const scopeKey of scopeKeys) {
+                    if (!isScopeKey(scopeKey)) {
+                        errors.push(`workspaceExports key '${scopeKey}' must be 4–32 hex chars`);
+                        continue;
+                    }
+                    const entry = entries[scopeKey];
+                    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+                        errors.push(`workspaceExports['${scopeKey}'] must be an object`);
+                        continue;
+                    }
+                    errors.push(...workspaceExportErrors(entry, `workspaceExports['${scopeKey}']`));
+                }
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            reason: `product_telemetry_state_malformed: ${errors.join('; ')}`,
+            nextAction: `Fix or delete ${filePath} (delete = consent returns to unset)`,
+        };
+    }
+    // Post-validation reconstruction from guard-narrowed fields — no `as` on
+    // the untrusted parsed object (rc-2). isConsent is a type guard; the
+    // optional-field spreads carry only guard-passing values. v1 export
+    // bookkeeping is deliberately NOT carried over (see module doc).
+    const state = {
+        consent: isConsent(obj.consent) ? obj.consent : 'unset',
+        consentVersion: typeof obj.consentVersion === 'string' ? obj.consentVersion : PRODUCT_TELEMETRY_CONSENT_VERSION,
+        ...(isValidTelemetrySecretHex(obj.telemetrySecret) ? { telemetrySecret: obj.telemetrySecret } : {}),
+        ...(isV2 && isPlainRecord(obj.workspaceExports)
+            ? {
+                workspaceExports: Object.fromEntries(Object.entries(obj.workspaceExports)
+                    .filter(([scopeKey, entry]) => isScopeKey(scopeKey) && isPlainRecord(entry))
+                    .map(([scopeKey, entry]) => {
+                    const record = entry;
+                    return [
+                        scopeKey,
+                        {
+                            ...(isOptionalIsoString(record.lastAttemptedAt) && record.lastAttemptedAt !== undefined ? { lastAttemptedAt: record.lastAttemptedAt } : {}),
+                            ...(isOptionalIsoString(record.lastSucceededAt) && record.lastSucceededAt !== undefined ? { lastSucceededAt: record.lastSucceededAt } : {}),
+                            ...(isOptionalIsoString(record.nextRetryAt) && record.nextRetryAt !== undefined ? { nextRetryAt: record.nextRetryAt } : {}),
+                            ...(isOptionalFailureCode(record.lastFailureCode) && record.lastFailureCode !== undefined ? { lastFailureCode: record.lastFailureCode } : {}),
+                            ...(isOptionalAttemptCount(record.dailyAttemptCount) && record.dailyAttemptCount !== undefined ? { dailyAttemptCount: record.dailyAttemptCount } : {}),
+                            ...(isOptionalAttemptBucketDate(record.attemptBucketDate) && record.attemptBucketDate !== undefined ? { attemptBucketDate: record.attemptBucketDate } : {}),
+                        },
+                    ];
+                })),
+            }
+            : {}),
+        schemaVersion: PRODUCT_TELEMETRY_CONTROL_SCHEMA_VERSION,
+    };
+    if (state.workspaceExports !== undefined && Object.keys(state.workspaceExports).length === 0) {
+        delete state.workspaceExports;
+    }
+    return { ok: true, state, existed: true };
+}
+/**
+ * Drop `workspaceExports` entries whose most recent activity (attempt or
+ * success) is older than WORKSPACE_EXPORT_STATE_MAX_AGE_DAYS. Bounded local
+ * operational state only — this is not a workspace history database.
+ */
+export function pruneWorkspaceExports(state, nowMs) {
+    const exports = state.workspaceExports;
+    if (exports === undefined)
+        return state;
+    const cutoff = nowMs - WORKSPACE_EXPORT_STATE_MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+    const kept = {};
+    for (const [scopeKey, entry] of Object.entries(exports)) {
+        const stamps = [entry.lastAttemptedAt, entry.lastSucceededAt].filter((s) => s !== undefined).map((s) => Date.parse(s));
+        const latest = stamps.length > 0 ? Math.max(...stamps) : Number.NEGATIVE_INFINITY;
+        if (Number.isNaN(latest) || latest < cutoff)
+            continue;
+        kept[scopeKey] = entry;
+    }
+    const next = { ...state };
+    if (Object.keys(kept).length > 0)
+        next.workspaceExports = kept;
+    else
+        delete next.workspaceExports;
+    return next;
+}
+/** Atomic write (temp file + rename) so a crash never truncates the state. */
+export function writeProductTelemetryControlState(homeDir, state) {
+    const filePath = getProductTelemetryStatePath(homeDir);
+    const dir = path.dirname(filePath);
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(tmpPath, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        fs.renameSync(tmpPath, filePath);
+        return { ok: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+            fs.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup; the write failure below is the loud signal
+        }
+        return {
+            ok: false,
+            reason: `product_telemetry_state_write_failed: ${message}`,
+            nextAction: `Check permissions on ${dir}`,
+        };
+    }
+}
+/** State after `pd telemetry enable`: explicit granted consent + secret. */
+export function grantedControlState(previous) {
+    return {
+        consent: 'granted',
+        consentVersion: PRODUCT_TELEMETRY_CONSENT_VERSION,
+        telemetrySecret: isValidTelemetrySecretHex(previous.telemetrySecret) ? previous.telemetrySecret : generateTelemetrySecretHex(),
+        ...(previous.workspaceExports !== undefined ? { workspaceExports: previous.workspaceExports } : {}),
+        schemaVersion: PRODUCT_TELEMETRY_CONTROL_SCHEMA_VERSION,
+    };
+}
+/**
+ * State after `pd telemetry disable`: consent denied and all export identity
+ * removed (SPEC §19). The explicit `denied` choice is preserved so PD never
+ * re-prompts.
+ */
+export function deniedControlState() {
+    return { consent: 'denied', consentVersion: PRODUCT_TELEMETRY_CONSENT_VERSION, schemaVersion: PRODUCT_TELEMETRY_CONTROL_SCHEMA_VERSION };
+}
+/**
+ * State after `pd telemetry reset` (SPEC §18): secret and export status are
+ * deleted — no future daily ID relates to previous ones. The consent choice
+ * is preserved; a fresh secret is generated only while telemetry remains
+ * enabled. Workspace bookkeeping keyed under the OLD secret's scope IDs is
+ * dropped with it (the IDs are meaningless under a new secret).
+ */
+export function resetControlState(previous) {
+    return {
+        consent: previous.consent,
+        consentVersion: PRODUCT_TELEMETRY_CONSENT_VERSION,
+        ...(previous.consent === 'granted' ? { telemetrySecret: generateTelemetrySecretHex() } : {}),
+        schemaVersion: PRODUCT_TELEMETRY_CONTROL_SCHEMA_VERSION,
+    };
+}

package/dist/product-telemetry/eligibility.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Production eligibility — Anonymous Product Telemetry v1
+ * (PRI-597, SPEC §35-§37).
+ *
+ * Environment suppression is evaluated independently of consent and the
+ * feature flag (both are AND-ed by the service). Every suppression reason is
+ * named in the result so `pd telemetry status` can show exactly why export is
+ * off (rc-9 — no silent suppression).
+ *
+ * Dev/CI/test detection follows the repository's explicit-marker philosophy
+ * (PD_E2E_MODE precedent): env markers and build-layout facts, never
+ * user-path heuristics.
+ */
+export type TelemetrySuppressionReason = 'env_kill_switch' | 'ci_environment' | 'vitest_environment' | 'e2e_mode' | 'workspace_environment' | 'install_layout_missing' | 'repo_checkout';
+export interface TelemetryEnvironmentInput {
+    env: {
+        /** PD_TELEMETRY_DISABLED raw value. */
+        killSwitch?: string;
+        /** process.env.CI raw value. */
+        ci?: string;
+        /** process.env.VITEST raw value (set by vitest workers). */
+        vitest?: string;
+        /** PD_E2E_MODE raw value. */
+        e2eMode?: string;
+    };
+    /** workspace.environment from .pd/config.yaml (PRI-587); 'unknown' when absent. */
+    workspaceEnvironment: 'production' | 'development' | 'demo' | 'test' | 'unknown';
+    /** Install layout mode; 'missing' = nothing installed. */
+    installMode: 'canonical' | 'legacy' | 'missing';
+    /** Directory of the executing telemetry module (repo-checkout detection). */
+    moduleDir: string;
+}
+export interface TelemetryEnvironmentResult {
+    suppressed: boolean;
+    reasons: TelemetrySuppressionReason[];
+}
+/** Boolean-style env flags follow the PD_SKIP_* convention: '1' or 'true'. */
+export declare function isEnvFlagActive(value: string | undefined): boolean;
+/**
+ * True when the executing module lives inside a PD monorepo checkout.
+ *
+ * Build-layout fact, not a path heuristic: an installed runtime (canonical
+ * `~/.pd/runtime/host-runtime/...` or legacy extension dir) never has a
+ * sibling `packages/principles-core` + `packages/host-runtime` tree, while
+ * a checkout always does. Prevents maintainer/AI development activity from
+ * polluting production telemetry.
+ */
+export declare function isRepoCheckoutModuleDir(moduleDir: string): boolean;
+/**
+ * Evaluate environment suppression. Kill switch outranks everything; the
+ * result lists every active reason.
+ */
+export declare function computeTelemetryEnvironment(input: TelemetryEnvironmentInput): TelemetryEnvironmentResult;

package/dist/product-telemetry/eligibility.js

@@ -0,0 +1,69 @@
+/**
+ * Production eligibility — Anonymous Product Telemetry v1
+ * (PRI-597, SPEC §35-§37).
+ *
+ * Environment suppression is evaluated independently of consent and the
+ * feature flag (both are AND-ed by the service). Every suppression reason is
+ * named in the result so `pd telemetry status` can show exactly why export is
+ * off (rc-9 — no silent suppression).
+ *
+ * Dev/CI/test detection follows the repository's explicit-marker philosophy
+ * (PD_E2E_MODE precedent): env markers and build-layout facts, never
+ * user-path heuristics.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Boolean-style env flags follow the PD_SKIP_* convention: '1' or 'true'. */
+export function isEnvFlagActive(value) {
+    return value === '1' || value === 'true';
+}
+function isTruthyEnv(value) {
+    return value !== undefined && value !== '' && value !== 'false' && value !== '0';
+}
+/**
+ * True when the executing module lives inside a PD monorepo checkout.
+ *
+ * Build-layout fact, not a path heuristic: an installed runtime (canonical
+ * `~/.pd/runtime/host-runtime/...` or legacy extension dir) never has a
+ * sibling `packages/principles-core` + `packages/host-runtime` tree, while
+ * a checkout always does. Prevents maintainer/AI development activity from
+ * polluting production telemetry.
+ */
+export function isRepoCheckoutModuleDir(moduleDir) {
+    let current = path.resolve(moduleDir);
+    for (let depth = 0; depth < 8; depth += 1) {
+        const hasCore = fs.existsSync(path.join(current, 'packages', 'principles-core'));
+        const hasHostRuntime = fs.existsSync(path.join(current, 'packages', 'host-runtime'));
+        if (hasCore && hasHostRuntime) {
+            return true;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return false;
+}
+/**
+ * Evaluate environment suppression. Kill switch outranks everything; the
+ * result lists every active reason.
+ */
+export function computeTelemetryEnvironment(input) {
+    const reasons = [];
+    if (isEnvFlagActive(input.env.killSwitch))
+        reasons.push('env_kill_switch');
+    if (isTruthyEnv(input.env.ci))
+        reasons.push('ci_environment');
+    if (isTruthyEnv(input.env.vitest))
+        reasons.push('vitest_environment');
+    if (input.env.e2eMode === '1')
+        reasons.push('e2e_mode');
+    if (input.workspaceEnvironment === 'test' || input.workspaceEnvironment === 'demo' || input.workspaceEnvironment === 'development') {
+        reasons.push('workspace_environment');
+    }
+    if (input.installMode === 'missing')
+        reasons.push('install_layout_missing');
+    if (isRepoCheckoutModuleDir(input.moduleDir))
+        reasons.push('repo_checkout');
+    return { suppressed: reasons.length > 0, reasons };
+}

package/dist/product-telemetry/exporter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+import type { ProductTelemetrySnapshotV1 } from '@principles/core/runtime-v2';
+export declare const DEFAULT_PRODUCT_TELEMETRY_ENDPOINT = "https://principles-website.pages.dev/api/product-telemetry/snapshot";
+export declare const PRODUCT_TELEMETRY_TIMEOUT_MS = 8000;
+export declare const PRODUCT_TELEMETRY_MAX_BODY_BYTES = 4096;
+export type TelemetryFailureCode = 'timeout' | 'network_error' | 'http_400' | 'http_429' | 'http_5xx' | 'http_unexpected_status' | 'invalid_response';
+export type TelemetryExportResult = {
+    ok: true;
+    status: number;
+} | {
+    ok: false;
+    code: TelemetryFailureCode;
+    retryable: boolean;
+};
+export type TelemetryFetchFn = (url: string, init: {
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+}) => Promise<{
+    status: number;
+}>;
+export interface ExportSnapshotArgs {
+    snapshot: ProductTelemetrySnapshotV1;
+    endpoint?: string;
+    timeoutMs?: number;
+    fetchFn?: TelemetryFetchFn;
+}
+/**
+ * Export one snapshot. Never throws; every failure maps to a coarse code
+ * with a retryable hint the service uses for backoff.
+ */
+export declare function exportSnapshot(args: ExportSnapshotArgs): Promise<TelemetryExportResult>;
+/**
+ * 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 declare function nextRetryDelayMs(previousFailureWithin24h: boolean): number;

package/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/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;