@evomap/evolver-core 2.0.0-beta.0

package/dist/hub/sanitize.js

@@ -0,0 +1,321 @@
+// Pre-publish sanitize (ported from v1 src/gep/sanitize.js): before any asset leaves for the hub, deep-redact
+// strings (30+ secret/path/email patterns) and scan for leaks (25 scanners + reverse env-value detection).
+// Pure functions, never throw — the block decision is returned to the chokepoint (bindings), which raises a
+// terminal PublishRejectedError. Command point: when redaction changes content the asset_id MUST be recomputed
+// (computeAssetId excludes asset_id by default), else the published body hash won't match its id and the hub
+// rejects it. See feedback_public_repo_no_internal_leak.
+import { computeAssetId } from '../wire/index.js';
+export const REDACTED = '[REDACTED]';
+/** Redaction patterns (ported verbatim from v1, 30 entries). A match is replaced with [REDACTED]. */
+const REDACT_PATTERNS = [
+    // API keys & tokens (generic)
+    /Bearer\s+[A-Za-z0-9-._~+/]+=*/g,
+    /"?node_secret"?\s*[:=]\s*["']?[A-Za-z0-9-._~+/]{16,}["']?/gi,
+    /sk-[A-Za-z0-9]{20,}/g,
+    /"?token"?[=:]\s*["']?[A-Za-z0-9-._~+/]{16,}["']?/gi,
+    /api[_-]?key[=:]\s*["']?[A-Za-z0-9-._~+/]{16,}["']?/gi,
+    /secret[=:]\s*["']?[A-Za-z0-9-._~+/]{16,}["']?/gi,
+    /password[=:]\s*["']?[^\s"',;)}\]]{6,}["']?/gi,
+    // GitHub tokens (ghp_, gho_, ghu_, ghs_, github_pat_)
+    /ghp_[A-Za-z0-9]{36,}/g,
+    /gho_[A-Za-z0-9]{36,}/g,
+    /ghu_[A-Za-z0-9]{36,}/g,
+    /ghs_[A-Za-z0-9]{36,}/g,
+    /github_pat_[A-Za-z0-9_]{22,}/g,
+    // AWS access keys
+    /AKIA[0-9A-Z]{16}/g,
+    // OpenAI / Anthropic tokens
+    /sk-proj-[A-Za-z0-9-_]{20,}/g,
+    /sk-ant-[A-Za-z0-9-_]{20,}/g,
+    // npm tokens
+    /npm_[A-Za-z0-9]{36,}/g,
+    // Slack tokens (bot/user/app/refresh/verification)
+    /xox[baprsv]-[A-Za-z0-9-]{10,}/g,
+    // JSON Web Tokens (header.payload.signature)
+    /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{20,}/g,
+    // Azure storage connection strings (redact the key field only)
+    /AccountKey=[^;\s]+/gi,
+    // Azure AD client secret + App Insights instrumentation key (value only)
+    /client_secret=[A-Za-z0-9~._-]{8,}/gi,
+    /instrumentationkey=[0-9a-fA-F-]{20,}/gi,
+    // Discord bot tokens: three base64url segments (uppercase leading char avoids matching dotted lowercase identifiers).
+    /\b[MNO][A-Za-z0-9_-]{23,}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27,}\b/g,
+    // Private keys
+    /-----BEGIN\s+(?:RSA\s+|EC\s+|DSA\s+|OPENSSH\s+)?PRIVATE\s+KEY-----[\s\S]*?-----END\s+(?:RSA\s+|EC\s+|DSA\s+|OPENSSH\s+)?PRIVATE\s+KEY-----/g,
+    // Basic auth in URLs (redact only credentials, keep :// and @)
+    /(?<=:\/\/)[^@\s]+:[^@\s]+(?=@)/g,
+    // Email addresses
+    /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+    // .env file references — only when the dot-env token looks like a real path (preceded by a path separator) or
+    // carries a suffix like `.env.production`. Bare prose mentions such as "Read from `.env` file" are intentionally
+    // NOT matched: the filename itself is a convention, not a secret, and over-redacting it strips useful debugging
+    // context from capsules without protecting anything the patterns above don't already cover (keys/tokens inside
+    // the env file). Ported from v1 src/gep/sanitize.js (PR #151).
+    /\.env\.[a-zA-Z]+\b/g,
+    /(?<=[\\/])\.env\b/g,
+];
+// Post-filter allowlist (ported from v1 src/gep/sanitize.js, PR #151): strings the patterns above — and the path
+// anonymizer below — WILL catch but that are not actually sensitive. If any entry matches a captured string it is
+// kept verbatim instead of being redacted / anonymized / flagged as a leak. Keeping this as a post-filter rather
+// than bolting more lookaheads into every pattern keeps the patterns readable and the carve-outs easy to audit.
+const REDACT_ALLOWLIST = [
+    // --- CI runner paths --- (well-known build infrastructure, no user PII)
+    /^\/home\/runner(?:[/]|$)/, // GitHub Actions Linux
+    /^\/Users\/runner(?:[/]|$)/, // GitHub Actions macOS
+    /^\/home\/circleci(?:[/]|$)/, // CircleCI Linux
+    /^\/Users\/distiller(?:[/]|$)/, // CircleCI macOS
+    /^\/home\/vsts(?:[/]|$)/, // Azure Pipelines
+    /^\/home\/travis(?:[/]|$)/, // Travis CI
+    /^\/home\/jenkins(?:[/]|$)/, // Jenkins default
+    // --- Bot / no-reply / SSH-alias addresses --- (not personal mailboxes)
+    // The domain MUST be anchored to a well-known public code host. An open noreply@<anything> allowlist would leak
+    // internal corp infra domains like noreply@internal-codename.corp (Bugbot PR #151 Low).
+    /^(?:noreply|no-reply|donotreply|do-not-reply)@(?:github\.com|users\.noreply\.github\.com|gitlab\.com|bitbucket\.org|npmjs\.com|claude\.ai|anthropic\.com)$/i,
+    /^[0-9]+\+[a-zA-Z0-9._-]+@users\.noreply\.github\.com$/i, // GitHub commit-author noreply (full digits+user form)
+    // The ssh_target scanner's local part is [a-zA-Z0-9_.-]{1,64} (no `+`), so `8275028+user@users.noreply.github.com`
+    // is captured as just `user@users.noreply.github.com` — the full-form anchor above can't match the truncated
+    // value. Allow any local part on this domain since the domain itself is by design non-personal (Bugbot PR #151
+    // round 2 Medium).
+    /^[a-zA-Z0-9_.-]+@users\.noreply\.github\.com$/i,
+    /^git@github\.com$/i, // SSH alias, not a real mailbox
+    /^git@gitlab\.com$/i,
+    /^git@bitbucket\.org$/i,
+];
+function isAllowlisted(match) {
+    for (const re of REDACT_ALLOWLIST)
+        if (re.test(match))
+            return true;
+    return false;
+}
+// Anonymize (not redact) local filesystem paths (#12): a file path is usually the gene's CONTENT ("fix
+// ~/proj/src/auth.ts"), not a secret — only the user/home prefix is PII. Strip the prefix to `~`, keeping the
+// rest of the path so the shared experience stays useful, instead of [REDACTED]-ing the whole thing.
+const ANONYMIZE_PATTERNS = [
+    [/\/(?:home|Users)\/[^/\s"',;)}\]]+/g, '~'], // /home/alice/proj → ~/proj
+    [/[A-Za-z]:\\Users\\[^\\/\s"',;)}\]]+/g, '~'], // C:\Users\alice\proj → ~\proj
+];
+/** Apply every redaction pattern (secrets → [REDACTED]) then anonymize local paths (~/...) to a single string. */
+export function redactString(s) {
+    if (typeof s !== 'string' || !s)
+        return s;
+    let out = s;
+    for (const p of REDACT_PATTERNS) {
+        p.lastIndex = 0;
+        out = out.replace(p, (m) => (isAllowlisted(m) ? m : REDACTED));
+    }
+    for (const [p, rep] of ANONYMIZE_PATTERNS) {
+        p.lastIndex = 0;
+        out = out.replace(p, (m) => (isAllowlisted(m) ? m : rep));
+    }
+    return out;
+}
+/** Deep redaction: recursively redact string values in objects/arrays (keys untouched). Returns a copy; does not mutate the input. */
+export function redactDeep(v) {
+    if (typeof v === 'string')
+        return redactString(v);
+    if (Array.isArray(v))
+        return v.map((x) => redactDeep(x));
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const [k, val] of Object.entries(v))
+            out[k] = redactDeep(val);
+        return out;
+    }
+    return v;
+}
+/**
+ * Redact a single asset and RECOMPUTE its asset_id (command point). When redaction changes content, the id must
+ * change with it, otherwise the published body and id disagree. computeAssetId excludes the asset_id field by
+ * default; on the rare null return we fall back to the original id.
+ */
+export function sanitizeAsset(asset) {
+    const redacted = redactDeep(asset);
+    const id = computeAssetId(redacted);
+    return { ...redacted, asset_id: id ?? asset.asset_id };
+}
+/** Leak scanners (ported verbatim from v1, 25 entries): each match yields an env-var replacement suggestion. */
+const LEAK_SCANNERS = [
+    { type: 'api_key', pattern: /sk-[A-Za-z0-9]{20,}/g, suggest: 'process.env.OPENAI_API_KEY' },
+    { type: 'api_key', pattern: /sk-proj-[A-Za-z0-9-_]{20,}/g, suggest: 'process.env.OPENAI_API_KEY' },
+    { type: 'api_key', pattern: /sk-ant-[A-Za-z0-9-_]{20,}/g, suggest: 'process.env.ANTHROPIC_API_KEY' },
+    { type: 'api_key', pattern: /AKIA[0-9A-Z]{16}/g, suggest: 'process.env.AWS_ACCESS_KEY_ID' },
+    { type: 'github_token', pattern: /ghp_[A-Za-z0-9]{36,}/g, suggest: 'process.env.GITHUB_TOKEN' },
+    { type: 'github_token', pattern: /github_pat_[A-Za-z0-9_]{22,}/g, suggest: 'process.env.GITHUB_TOKEN' },
+    { type: 'npm_token', pattern: /npm_[A-Za-z0-9]{36,}/g, suggest: 'process.env.NPM_TOKEN' },
+    { type: 'slack_token', pattern: /xox[baprsv]-[A-Za-z0-9-]{10,}/g, suggest: 'process.env.SLACK_TOKEN' },
+    { type: 'jwt', pattern: /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{20,}/g, suggest: 'process.env.JWT' },
+    { type: 'azure_key', pattern: /AccountKey=[^;\s]+/gi, suggest: 'process.env.AZURE_STORAGE_KEY' },
+    { type: 'azure_client_secret', pattern: /client_secret=[A-Za-z0-9~._-]{8,}/gi, suggest: 'process.env.AZURE_CLIENT_SECRET' },
+    { type: 'azure_instrumentation_key', pattern: /instrumentationkey=[0-9a-fA-F-]{20,}/gi, suggest: 'process.env.APPINSIGHTS_INSTRUMENTATIONKEY' },
+    { type: 'discord_token', pattern: /\b[MNO][A-Za-z0-9_-]{23,}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27,}\b/g, suggest: 'process.env.DISCORD_TOKEN' },
+    { type: 'bearer_token', pattern: /Bearer\s+[A-Za-z0-9-._~+/]{20,}=*/g, suggest: 'process.env.AUTH_TOKEN' },
+    { type: 'proxy_token', pattern: /"?token"?[=:]\s*["']?[A-Za-z0-9-._~+/]{16,}["']?/gi, suggest: 'proxy token (ephemeral, stored in settings.json)' },
+    { type: 'private_key', pattern: /-----BEGIN\s+(?:RSA\s+|EC\s+|DSA\s+|OPENSSH\s+)?PRIVATE\s+KEY-----/g, suggest: 'process.env.PRIVATE_KEY_PATH' },
+    { type: 'db_url', pattern: /(?:mongodb|postgres|postgresql|mysql|redis|amqp):\/\/[^\s"',;)}\]]{10,}/gi, suggest: 'process.env.DATABASE_URL' },
+    { type: 'local_path', pattern: /\/home\/[a-zA-Z0-9_.-]+\//g, suggest: 'process.env.HOME' },
+    { type: 'local_path', pattern: /\/Users\/[a-zA-Z0-9_.-]+\//g, suggest: 'process.env.HOME' },
+    { type: 'local_path', pattern: /[A-Z]:\\Users\\[a-zA-Z0-9_.-]+\\/g, suggest: 'process.env.USERPROFILE' },
+    { type: 'internal_ip', pattern: /\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})(?::\d{2,5})?\b/g, suggest: 'process.env.SERVICE_HOST' },
+    // Bounded quantifiers ({1,64}/{1,255}/{2,24}) instead of unbounded `+`: the unbounded user/host classes against
+    // a required `@`/`.` anchor backtrack O(n^2) on long untrusted hub content (100k took ~6s — a real ReDoS, #198).
+    // The bounds cover every realistic ssh target (usernames <=64, hosts <=255, TLDs <=24) and make the scan linear.
+    { type: 'ssh_target', pattern: /[a-zA-Z0-9_.-]{1,64}@(?:(?:\d{1,3}\.){3}\d{1,3}|[a-zA-Z0-9.-]{1,255}\.[a-zA-Z]{2,24})/g, suggest: 'process.env.SSH_HOST' },
+    { type: 'password', pattern: /password[=:]\s*["']?[^\s"',;)}\]]{6,}["']?/gi, suggest: 'process.env.PASSWORD' },
+    { type: 'secret', pattern: /secret[=:]\s*["']?[A-Za-z0-9-._~+/]{16,}["']?/gi, suggest: 'process.env.SECRET' },
+    { type: 'basic_auth', pattern: /:\/\/[^@\s:]+:[^@\s]+@/g, suggest: 'process.env.SERVICE_URL' },
+];
+/** Env keys skipped by the reverse-value scan (non-sensitive; ported verbatim from v1). */
+const ENV_SCAN_SKIP_KEYS = new Set([
+    'PATH', 'HOME', 'SHELL', 'TERM', 'LANG', 'USER', 'LOGNAME',
+    'PWD', 'OLDPWD', 'SHLVL', 'HOSTNAME', 'DISPLAY', 'EDITOR',
+    'PAGER', 'LESS', 'LS_COLORS', 'COLORTERM', 'TERM_PROGRAM',
+    'XDG_SESSION_ID', 'XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS',
+    'SSH_AUTH_SOCK', 'SSH_AGENT_PID', '_',
+]);
+const ENV_VALUE_FILESYSTEM_PATH_RE = /^(\/|[A-Za-z]:\\)/;
+const ENV_VALUE_URL_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+const SENSITIVE_ENV_KEY_PARTS = new Set([
+    'WEBHOOK', 'TOKEN', 'SECRET', 'PASSWORD', 'PASS', 'PASSWD', 'PASSPHRASE',
+    'KEY', 'CREDENTIAL', 'CREDENTIALS', 'SIGNATURE', 'SIGNED', 'DSN', 'BEARER',
+    'COOKIE', 'SESSION', 'CERT', 'CERTIFICATE',
+]);
+const SENSITIVE_ENV_KEY_RE = /WEBHOOK|TOKEN|SECRET|PASSWORD|CREDENTIAL|SIGNATURE|SIGNED|DSN|BEARER|COOKIE|SESSION|APIKEY|ACCESSKEY|PRIVATEKEY|CERTIFICATE/;
+const HIGH_RISK_URL_QUERY_KEYS = new Set([
+    'token', 'access_token', 'auth', 'authorization', 'api_key', 'apikey', 'key',
+    'secret', 'signature', 'sig', 'signed', 'x-amz-signature', 'x-amz-credential',
+    'x-amz-security-token', 'x-goog-signature', 'x-goog-credential',
+    'sharedaccesssignature',
+]);
+function normalizeEnvKey(key) {
+    const normalized = key.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return normalized || key.toUpperCase();
+}
+function isFilesystemPathEnvValue(value) {
+    return ENV_VALUE_FILESYSTEM_PATH_RE.test(value);
+}
+function isUrlEnvValue(value) {
+    return ENV_VALUE_URL_RE.test(value);
+}
+function isSensitiveEnvKey(key) {
+    const normalized = normalizeEnvKey(key);
+    const parts = normalized.split(/[^A-Z0-9]+/).filter(Boolean);
+    if (parts.some((part) => SENSITIVE_ENV_KEY_PARTS.has(part)))
+        return true;
+    return SENSITIVE_ENV_KEY_RE.test(normalized);
+}
+function isHighRiskUrlEnvValue(value) {
+    if (!isUrlEnvValue(value))
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.username || parsed.password)
+        return true;
+    const hostname = parsed.hostname.toLowerCase();
+    const pathname = parsed.pathname.toLowerCase();
+    if (/(^|\.)hooks?\./.test(hostname) || /(^|\.)webhooks?\./.test(hostname))
+        return true;
+    if (/\/(?:api\/)?webhooks?\//.test(pathname) || /\/hooks?\//.test(pathname))
+        return true;
+    if (/\/(?:tokens?|secrets?|signed|signatures?|credentials?)\//.test(pathname))
+        return true;
+    for (const queryKey of parsed.searchParams.keys()) {
+        if (HIGH_RISK_URL_QUERY_KEYS.has(queryKey.toLowerCase()))
+            return true;
+    }
+    return false;
+}
+function shouldSkipEnvValueReverseScan(key, value) {
+    if (isSensitiveEnvKey(key))
+        return false;
+    if (isFilesystemPathEnvValue(value))
+        return true;
+    if (isUrlEnvValue(value) && !isHighRiskUrlEnvValue(value))
+        return true;
+    return false;
+}
+const clip = (s) => (s.length > 60 ? s.slice(0, 57) + '...' : s);
+/** Pattern-scan content for sensitive info. Does not mutate content; returns a structured result. */
+export function scanForLeaks(content) {
+    if (typeof content !== 'string' || !content)
+        return { found: false, leaks: [] };
+    const leaks = [];
+    const seen = new Set();
+    for (const scanner of LEAK_SCANNERS) {
+        scanner.pattern.lastIndex = 0;
+        let m;
+        while ((m = scanner.pattern.exec(content)) !== null) {
+            const val = m[0];
+            // Apply the same allowlist redactString uses: CI runner roots and bot/no-reply/SSH-alias addresses are not
+            // leaks. Without this, strict-mode sanitizeBundle would block a publish over a `/home/runner/` path or
+            // `noreply@github.com` (an ssh_target) — exactly the false positives the allowlist exists to fix, and a
+            // contradiction with redactString, which keeps them verbatim (Bugbot PR #151 Medium).
+            if (isAllowlisted(val))
+                continue;
+            const key = scanner.type + ':' + val;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            leaks.push({ type: scanner.type, value: clip(val), suggestion: scanner.suggest });
+        }
+    }
+    return { found: leaks.length > 0, leaks };
+}
+/** Reverse detection: if any process.env value (>=8 chars) appears verbatim in content, an env value was hardcoded and should be replaced with the env reference. */
+export function detectEnvValueLeaks(content, env) {
+    if (typeof content !== 'string' || !content)
+        return [];
+    const leaks = [];
+    for (const [key, val] of Object.entries(env)) {
+        if (!val || val.length < 8)
+            continue;
+        if (ENV_SCAN_SKIP_KEYS.has(normalizeEnvKey(key)))
+            continue;
+        // Env paths and ordinary URLs are often reproducible runtime metadata; sensitive keys and high-risk URLs still scan.
+        if (shouldSkipEnvValueReverseScan(key, val))
+            continue;
+        if (content.includes(val))
+            leaks.push({ type: 'env_value_leak', value: REDACTED, suggestion: 'process.env.' + key });
+    }
+    return leaks;
+}
+/** Full leak check: pattern scan + reverse env-value detection. */
+export function fullLeakCheck(content, env) {
+    const scan = scanForLeaks(content);
+    const envLeaks = detectEnvValueLeaks(content, env);
+    const all = scan.leaks.concat(envLeaks);
+    return { found: all.length > 0, leaks: all };
+}
+/** Leak types that are PII (anonymized, not credentials) and so must NOT hard-block a strict publish (#12). */
+const PII_ONLY_LEAK_TYPES = new Set(['local_path']);
+/** Read the leak-check mode from env (EVOLVER_LEAK_CHECK, default strict, matching v1). */
+export function leakCheckModeFromEnv(env) {
+    const v = (env['EVOLVER_LEAK_CHECK'] ?? '').toLowerCase();
+    return v === 'warn' || v === 'off' ? v : 'strict';
+}
+/**
+ * Pre-publish sanitize of a bundle (pure, never throws):
+ * 1) mode != off: scan the ORIGINAL (pre-redaction) content for leaks; strict + found → blocked=true (chokepoint refuses); warn → flag only.
+ * 2) REGARDLESS of mode, always deep-redact every asset + recompute asset_id (the leak-proof floor; off only skips the scan, not the redaction).
+ */
+export function sanitizeBundle(bundle, opts) {
+    const mode = opts.mode ?? leakCheckModeFromEnv(opts.env);
+    let leaks = [];
+    if (mode !== 'off') {
+        const combined = bundle.map((a) => JSON.stringify(a)).join('');
+        leaks = fullLeakCheck(combined, opts.env).leaks;
+    }
+    // #12: a bare local path is PII (anonymized to ~/ by the redaction floor), not a credential — it must not
+    // hard-block a publish in strict mode. Real secrets (everything else) still block. Path leaks stay reported.
+    const blocked = mode === 'strict' && leaks.some((l) => !PII_ONLY_LEAK_TYPES.has(l.type));
+    const sanitized = bundle.map((a) => sanitizeAsset(a));
+    return { bundle: sanitized, blocked, leaks, mode };
+}
+/** Collapse a leak list into a one-line human-readable summary (for logs / rejection reason). */
+export function summarizeLeaks(leaks) {
+    return leaks.map((l) => `${l.type}→${l.suggestion}`).join('; ');
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export declare const PACKAGE = "@evomap/evolver-core";
+export * as schema from './schema/index.js';
+export * as wire from './wire/index.js';
+export * as events from './events/public.js';
+export * as signatures from './signatures/index.js';
+export * as trigger from './trigger/index.js';
+export * as observers from './observers/index.js';
+export * as cycle from './cycle/index.js';
+export * as daemon from './daemon/index.js';
+export * as material from './material/index.js';
+export * as mailbox from './mailbox/index.js';
+export * as assetstore from './assetstore/index.js';
+export * as strategy from './strategy/index.js';
+export * as algo from './algo/index.js';
+export * as personality from './personality/index.js';
+export * as signals from './signals/index.js';
+export * as verify from './verify/index.js';
+export * as exec from './exec/index.js';
+export * as bootstrap from './bootstrap/index.js';
+export * as hooks from './hooks/index.js';
+export * as benchmark from './benchmark/index.js';
+export * as workflow from './workflow/index.js';
+export * as hub from './hub/index.js';
+export * as shadow from './shadow/index.js';
+export * as ops from './ops/index.js';
+export * as util from './util/index.js';
+export * as trace from './trace/index.js';

package/dist/index.js

@@ -0,0 +1,27 @@
+export const PACKAGE = '@evomap/evolver-core';
+export * as schema from './schema/index.js';
+export * as wire from './wire/index.js';
+export * as events from './events/public.js';
+export * as signatures from './signatures/index.js';
+export * as trigger from './trigger/index.js';
+export * as observers from './observers/index.js';
+export * as cycle from './cycle/index.js';
+export * as daemon from './daemon/index.js';
+export * as material from './material/index.js';
+export * as mailbox from './mailbox/index.js';
+export * as assetstore from './assetstore/index.js';
+export * as strategy from './strategy/index.js';
+export * as algo from './algo/index.js';
+export * as personality from './personality/index.js';
+export * as signals from './signals/index.js';
+export * as verify from './verify/index.js';
+export * as exec from './exec/index.js';
+export * as bootstrap from './bootstrap/index.js';
+export * as hooks from './hooks/index.js';
+export * as benchmark from './benchmark/index.js';
+export * as workflow from './workflow/index.js';
+export * as hub from './hub/index.js';
+export * as shadow from './shadow/index.js';
+export * as ops from './ops/index.js';
+export * as util from './util/index.js';
+export * as trace from './trace/index.js';

package/dist/mailbox/catalog.d.ts

@@ -0,0 +1,17 @@
+export type Direction = 'outbound' | 'inbound' | 'local';
+export type Handler = 'core' | 'proxy' | 'agent';
+export type TtlClass = 'control' | 'default';
+export interface MessageSpec {
+    direction: Direction;
+    handler: Handler;
+    feedsMaterial: boolean;
+    ttlClass: TtlClass;
+}
+export declare class UnknownMessageTypeError extends Error {
+    readonly type: string;
+    constructor(type: string);
+}
+/** 三态消息目录单一来源 (mailbox 草案 §4). handler: core 确定性 / proxy non-agentic hub往返 / agent 需智能. */
+export declare const MESSAGE_CATALOG: Readonly<Record<string, MessageSpec>>;
+export declare function specForType(type: string): MessageSpec | undefined;
+export declare function assertKnownType(type: string): MessageSpec;

package/dist/mailbox/catalog.js

@@ -0,0 +1,53 @@
+export class UnknownMessageTypeError extends Error {
+    type;
+    constructor(type) {
+        super(`未知 mailbox 消息类型: ${type}`);
+        this.type = type;
+        this.name = 'UnknownMessageTypeError';
+    }
+}
+/** 三态消息目录单一来源 (mailbox 草案 §4). handler: core 确定性 / proxy non-agentic hub往返 / agent 需智能. */
+export const MESSAGE_CATALOG = {
+    // agent→hub (outbound)
+    asset_submit: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
+    task_claim: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
+    task_complete: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
+    task_subscribe: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'control' },
+    task_unsubscribe: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'control' },
+    atp_order: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
+    atp_deliver: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
+    atp_settle: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
+    proxy_trace: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
+    // hub→agent / local (inbound)
+    pending_materials: { direction: 'local', handler: 'agent', feedsMaterial: false, ttlClass: 'default' },
+    asset_publish_result: { direction: 'inbound', handler: 'core', feedsMaterial: false, ttlClass: 'default' }, // 拒绝进 Material 在 dispatch 决定
+    pending_evomap_task: { direction: 'inbound', handler: 'agent', feedsMaterial: false, ttlClass: 'default' },
+    task_available: { direction: 'inbound', handler: 'agent', feedsMaterial: false, ttlClass: 'default' },
+    work_assigned: { direction: 'inbound', handler: 'agent', feedsMaterial: false, ttlClass: 'default' },
+    dialog_message: { direction: 'inbound', handler: 'agent', feedsMaterial: true, ttlClass: 'default' },
+    peer_review_request: { direction: 'inbound', handler: 'agent', feedsMaterial: true, ttlClass: 'default' },
+    bounty_review_requested: { direction: 'inbound', handler: 'agent', feedsMaterial: true, ttlClass: 'default' },
+    dm: { direction: 'inbound', handler: 'agent', feedsMaterial: true, ttlClass: 'default' },
+    feature_flag_update: { direction: 'inbound', handler: 'core', feedsMaterial: false, ttlClass: 'control' },
+    force_update: { direction: 'inbound', handler: 'core', feedsMaterial: false, ttlClass: 'control' },
+    overdue_tasks: { direction: 'inbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'control' },
+    heartbeat: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'control' },
+    credential_rotation: { direction: 'inbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'control' },
+    trace_collection_config: { direction: 'inbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'control' },
+    proxy_trace_config: { direction: 'inbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'control' },
+    skill_md_update: { direction: 'inbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
+};
+const PREFIX_SPECS = [
+    ['council.', { direction: 'inbound', handler: 'agent', feedsMaterial: true, ttlClass: 'default' }],
+    ['deliberation.', { direction: 'inbound', handler: 'agent', feedsMaterial: true, ttlClass: 'default' }],
+    ['swarm.', { direction: 'inbound', handler: 'agent', feedsMaterial: false, ttlClass: 'default' }], // 仅结论进, dispatch 决定
+];
+export function specForType(type) {
+    return MESSAGE_CATALOG[type] ?? PREFIX_SPECS.find(([pre]) => type.startsWith(pre))?.[1];
+}
+export function assertKnownType(type) {
+    const s = specForType(type);
+    if (!s)
+        throw new UnknownMessageTypeError(type);
+    return s;
+}

package/dist/mailbox/daemon.d.ts

@@ -0,0 +1,48 @@
+import { DrainController } from '../daemon/drain.js';
+import type { MailboxStore } from './store.js';
+import type { Dispatcher, DispatchResult } from './dispatch.js';
+import type { AgentWaker, WakeOutcome } from './wake.js';
+import type { Handler } from './catalog.js';
+export interface MailboxDaemonDeps {
+    store: MailboxStore;
+    dispatcher: Dispatcher;
+    waker?: AgentWaker;
+    /** 闸2 drain: 注入共享或自建. */
+    drain?: DrainController;
+    /** 单写文件锁(可选); 防多 daemon 同时 pump 同信箱. */
+    lockPath?: string;
+    now: () => number;
+    /** 每 N 个 tick 跑一次 TTL 扫描(默认 60). */
+    expireEveryTicks?: number;
+    pumpHandlers?: Handler[];
+}
+export interface TickReport {
+    skipped: boolean;
+    dispatched: DispatchResult[];
+    woken: WakeOutcome[];
+    expired: number;
+}
+/**
+ * Mailbox daemon 循环(M2-9), 整进军杰附录 A 四闸:
+ * - 闸1 cycle-local: 每 tick 独立(dispatcher 无跨 tick 可变态).
+ * - 闸2 drain: draining 时拒新 tick, 排空进行中再退.
+ * - 闸3 watchdog: 暴露 lastWriteAt 供外部 watchdog 判挂死.
+ * - 闸4 幂等: dispatcher 经 store idempotency 表(无时间窗)去重副作用.
+ * 单写: 可选 O_EXCL 文件锁.
+ */
+export declare class MailboxDaemon {
+    private readonly deps;
+    private readonly drain;
+    private lastActivityAt;
+    private ticks;
+    private locked;
+    constructor(deps: MailboxDaemonDeps);
+    start(): void;
+    /** 一个处理周期: pump(core+proxy) + waker.tick + 周期性 TTL 扫描. */
+    tick(): Promise<TickReport>;
+    /** 闸3: root_events/活动最后写入时间, 喂外部 Watchdog. */
+    lastWriteAt(): number;
+    /** 闸2: 优雅停机 — 停接新 tick, 排空进行中, 释放锁. */
+    stop(): Promise<void>;
+    get isDraining(): boolean;
+}

package/dist/mailbox/daemon.js

@@ -0,0 +1,61 @@
+import { acquireLock, releaseLock } from '../util/fileLock.js';
+import { DrainController } from '../daemon/drain.js';
+/**
+ * Mailbox daemon 循环(M2-9), 整进军杰附录 A 四闸:
+ * - 闸1 cycle-local: 每 tick 独立(dispatcher 无跨 tick 可变态).
+ * - 闸2 drain: draining 时拒新 tick, 排空进行中再退.
+ * - 闸3 watchdog: 暴露 lastWriteAt 供外部 watchdog 判挂死.
+ * - 闸4 幂等: dispatcher 经 store idempotency 表(无时间窗)去重副作用.
+ * 单写: 可选 O_EXCL 文件锁.
+ */
+export class MailboxDaemon {
+    deps;
+    drain;
+    lastActivityAt;
+    ticks = 0;
+    locked = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.drain = deps.drain ?? new DrainController();
+        this.lastActivityAt = deps.now();
+    }
+    start() {
+        if (this.deps.lockPath && !this.locked) {
+            acquireLock(this.deps.lockPath);
+            this.locked = true;
+        }
+        this.lastActivityAt = this.deps.now();
+    }
+    /** 一个处理周期: pump(core+proxy) + waker.tick + 周期性 TTL 扫描. */
+    async tick() {
+        if (!this.drain.acceptCycle())
+            return { skipped: true, dispatched: [], woken: [], expired: 0 };
+        this.drain.beginCycle();
+        try {
+            const now = this.deps.now();
+            const dispatched = await this.deps.dispatcher.pump({ handlers: this.deps.pumpHandlers });
+            const woken = this.deps.waker ? await this.deps.waker.tick() : [];
+            let expired = 0;
+            this.ticks += 1;
+            if (this.ticks % (this.deps.expireEveryTicks ?? 60) === 0)
+                expired = this.deps.store.expireOld(now);
+            if (dispatched.length > 0 || woken.some((w) => w.action !== 'none') || expired > 0)
+                this.lastActivityAt = now;
+            return { skipped: false, dispatched, woken, expired };
+        }
+        finally {
+            this.drain.endCycle();
+        }
+    }
+    /** 闸3: root_events/活动最后写入时间, 喂外部 Watchdog. */
+    lastWriteAt() { return this.lastActivityAt; }
+    /** 闸2: 优雅停机 — 停接新 tick, 排空进行中, 释放锁. */
+    async stop() {
+        await this.drain.drain();
+        if (this.deps.lockPath && this.locked) {
+            releaseLock(this.deps.lockPath);
+            this.locked = false;
+        }
+    }
+    get isDraining() { return this.drain.isDraining; }
+}

package/dist/mailbox/dispatch.d.ts

@@ -0,0 +1,46 @@
+import type { Envelope } from './envelope.js';
+import type { Handler } from './catalog.js';
+import type { MailboxStore } from './store.js';
+export interface DispatchResult {
+    id: string;
+    handler: Handler;
+    handled: boolean;
+    fedMaterial: boolean;
+    note?: string;
+}
+/** 三类 handler 实现; 由集成层注入. core=确定性, proxy=hub 往返, agent=智能(嵌入式 runtime 时直接处理). */
+export interface DispatchHandlers {
+    core: (e: Envelope) => Promise<unknown> | unknown;
+    proxy: (e: Envelope) => Promise<unknown> | unknown;
+    agent: (e: Envelope) => Promise<unknown> | unknown;
+}
+export interface DispatcherDeps {
+    store: MailboxStore;
+    handlers: DispatchHandlers;
+    /** 选择性 Material 投喂: dispatch 判定通过才调用(集成层把 envelope→Material). */
+    onMaterial?: (e: Envelope) => void | Promise<void>;
+    now: () => number;
+}
+/**
+ * 选择性 Material 判定(M2-7). 默认遵目录 feedsMaterial; 两类在 dispatch 决定:
+ * - asset_publish_result: 仅 rejected 进(失败=养料 #40); 通过无需.
+ * - swarm.*: 仅带结论的进; 中间消息不进.
+ */
+export declare function shouldFeedMaterial(e: Envelope): boolean;
+/**
+ * 三-handler 分派器(M2-7). 谁 claim 谁 complete:
+ * - daemon 侧 pump core+proxy(确定性/hub 往返).
+ * - agent 类常由外部 runtime 经 IPC(M2-6) claim+complete; 嵌入式可显式 pump ['agent'].
+ */
+export declare class Dispatcher {
+    private readonly deps;
+    constructor(deps: DispatcherDeps);
+    dispatchOne(e: Envelope): Promise<DispatchResult>;
+    /** 拉一批并分派. 默认 daemon 侧 core+proxy; agent 由 runtime 经 IPC 拉取. */
+    pump(opts?: {
+        handlers?: Handler[];
+        limit?: number;
+        leaseMs?: number;
+        runtimeNamespace?: string;
+    }): Promise<DispatchResult[]>;
+}