productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/discoverySources.js

@@ -0,0 +1,322 @@
+const PROVIDER_HOSTS = {
+    // notes.granola.ai is Granola's share-link host — the owner pastes exactly these
+    // (customer-signal-inbox-v0: its absence forced source_url null across the whole
+    // first batch and refused an owner-approved ingestion).
+    granola: ["app.granola.ai", "granola.ai", "notes.granola.ai"],
+    fakecalls: ["review.fakecalls.test"],
+    // Fireflies transcript links are believed path-based under fireflies.ai
+    // (fireflies-discovery-connector-v0 R-006 — belief owned by the packet's
+    // feasibility task): the global no-query rule applies, so hosts alone are
+    // declared and no ProviderLinkForm is needed.
+    fireflies: ["app.fireflies.ai", "fireflies.ai"],
+    // notion-discovery-connector-v0 R-006: Notion's canonical page form is
+    // https://www.notion.so/<page-id> — no query string. The global no-query rule
+    // is what refuses tokenized share links (they carry query parameters); the
+    // V0 stance is refuse, never de-tokenize, until the feasibility task (T-001)
+    // verifies the exact link semantics.
+    notion: ["notion.so", "www.notion.so"],
+};
+const PROVIDER_LINK_FORMS = {
+    // Belief, owned by the packet's feasibility task: Gong links a call as
+    // https://app.gong.io/call?id=<call-id> (or under a company subdomain).
+    gong: { hosts: ["app.gong.io"], host_suffix: ".app.gong.io", path: "/call", query: { name: "id", pattern: /^[A-Za-z0-9_-]{4,64}$/ } },
+    // Microsoft Teams declares NO host and NO link form yet
+    // (microsoft-teams-discovery-connector-v0 R-006): Graph join URLs are
+    // tokenized and are never stable links, and the canonical meeting/recording
+    // link form is owned by the packet's feasibility task. Until that task
+    // verifies a form, every Teams URL is refused here — never cleaned — and
+    // the adapter reports stable_link: false. Other providers stay unchanged.
+};
+// Path-based canonical links on a per-workspace subdomain
+// (zendesk-discovery-connector-v0 R-006): the host is exactly one subdomain
+// label plus the declared suffix, the path is the declared canonical form,
+// and the global no-query/no-fragment rules apply unchanged — a tokenized or
+// authenticated link is refused, never cleaned. Providers without an entry
+// keep the exact-host rule byte-for-byte.
+const PROVIDER_PATH_FORMS = {
+    // Belief, owned by the packet's feasibility task: Zendesk links a ticket as
+    // https://<subdomain>.zendesk.com/agent/tickets/<numeric-id>.
+    zendesk: { suffix: ".zendesk.com", path: /^\/agent\/tickets\/\d+$/ },
+    // Belief, owned by the packet's feasibility task (T-001): Zoom links a
+    // recording as https://<subdomain>.zoom.us/recording/<id>. Because the
+    // canonical form carries the identifier in the path and needs no query
+    // parameter, Zoom declares no `ProviderLinkForm`; tokenized variants
+    // (`/rec/share/...`, `?pwd=`, `?access_token=`) match no rule and are
+    // refused, never cleaned.
+    zoom: { suffix: ".zoom.us", path: /^\/recording\/[A-Za-z0-9_-]{16,128}$/ },
+};
+// Path-based canonical links on a per-workspace subdomain
+// (zendesk-discovery-connector-v0 R-006): the host is exactly one subdomain
+// label plus the declared suffix, the path is the declared canonical form,
+// and the global no-query/no-fragment rules apply unchanged — a tokenized or
+// authenticated link is refused, never cleaned. Providers without an entry
+// keep the exact-host rule byte-for-byte.
+export function providerLinkForm(provider) {
+    return PROVIDER_LINK_FORMS[provider.toLowerCase()];
+}
+const PROVIDER_PATH_TEMPLATE_FORMS = {
+    // Belief, owned by the packet's feasibility task: Slack permalinks are
+    // https://<workspace>.slack.com/archives/<channel>/p<ts> where the ts is the
+    // message timestamp with the dot removed — a 10-digit epoch second plus a
+    // 6-digit microsecond field, 16 digits total. The path-template grammar
+    // matches whole segments only, so the `p` prefix lives inside the
+    // placeholder's own pattern.
+    slack: { hosts: ["slack.com"], host_suffix: ".slack.com", template: "/archives/<channel>/<permalink_ts>", placeholders: { channel: /^C[A-Za-z0-9]{8,}$/, permalink_ts: /^p\d{16}$/ } },
+};
+const PATH_PLACEHOLDER = /^<(\w+)>$/;
+function sanitizeDeclaredPathTemplateForm(provider, url, form) {
+    const host = url.hostname.toLowerCase();
+    const hostOk = form.hosts.includes(host) ||
+        (form.host_suffix !== undefined && host.endsWith(form.host_suffix) && /^[a-z0-9-]+$/.test(host.slice(0, -form.host_suffix.length)));
+    if (!hostOk)
+        throw new Error(`stable URL must use an approved host for ${provider}`);
+    if (url.hash)
+        throw new Error("stable URL must not contain a fragment");
+    if (url.search)
+        throw new Error(`stable URL must not carry a query string for ${provider}`);
+    const templateSegments = form.template.split("/").filter(Boolean);
+    const actualSegments = url.pathname.split("/").filter(Boolean);
+    if (templateSegments.length !== actualSegments.length)
+        throw new Error(`stable URL must use the canonical ${provider} path`);
+    const captured = {};
+    for (const [index, segment] of templateSegments.entries()) {
+        const placeholder = PATH_PLACEHOLDER.exec(segment);
+        if (!placeholder) {
+            if (segment !== actualSegments[index])
+                throw new Error(`stable URL must use the canonical ${provider} path`);
+            continue;
+        }
+        const pattern = form.placeholders[placeholder[1]];
+        if (!pattern || !pattern.test(actualSegments[index]))
+            throw new Error(`stable URL ${placeholder[1]} does not look like a ${provider} identifier`);
+        captured[placeholder[1]] = actualSegments[index];
+    }
+    const rebuilt = templateSegments.map((segment) => {
+        const placeholder = PATH_PLACEHOLDER.exec(segment);
+        return placeholder ? captured[placeholder[1]] : segment;
+    }).join("/");
+    return `https://${host}/${rebuilt}`;
+}
+function sanitizeDeclaredLinkForm(provider, url, form) {
+    const host = url.hostname.toLowerCase();
+    const hostOk = form.hosts.includes(host) ||
+        (form.host_suffix !== undefined && host.endsWith(form.host_suffix) && /^[a-z0-9-]+$/.test(host.slice(0, -form.host_suffix.length)));
+    if (!hostOk)
+        throw new Error(`stable URL must use an approved host for ${provider}`);
+    if (url.hash)
+        throw new Error("stable URL must not contain a fragment");
+    if (url.pathname !== form.path)
+        throw new Error(`stable URL must use the canonical ${provider} path`);
+    const params = [...url.searchParams.entries()];
+    if (params.length !== 1 || params[0][0] !== form.query.name)
+        throw new Error(`stable URL must carry exactly the ${form.query.name} parameter for ${provider}`);
+    const id = params[0][1];
+    if (!form.query.pattern.test(id))
+        throw new Error(`stable URL ${form.query.name} does not look like a ${provider} identifier`);
+    return `https://${host}${form.path}?${form.query.name}=${id}`;
+}
+export function sanitizeDiscoveryStableUrl(provider, value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("stable URL is invalid");
+    }
+    if (url.protocol !== "https:")
+        throw new Error("stable URL must use HTTPS");
+    if (url.username || url.password)
+        throw new Error("stable URL must not contain credentials");
+    const templateForm = PROVIDER_PATH_TEMPLATE_FORMS[provider.toLowerCase()];
+    if (templateForm)
+        return sanitizeDeclaredPathTemplateForm(provider, url, templateForm);
+    const form = PROVIDER_LINK_FORMS[provider.toLowerCase()];
+    if (form)
+        return sanitizeDeclaredLinkForm(provider, url, form);
+    if (url.search)
+        throw new Error("stable URL must not contain a query string");
+    if (url.hash)
+        throw new Error("stable URL must not contain a fragment");
+    const pathForm = PROVIDER_PATH_FORMS[provider.toLowerCase()];
+    if (pathForm) {
+        const host = url.hostname.toLowerCase();
+        const hostOk = host.endsWith(pathForm.suffix) && /^[a-z0-9-]+$/.test(host.slice(0, -pathForm.suffix.length));
+        if (!hostOk)
+            throw new Error(`stable URL must use an approved host for ${provider}`);
+        if (!pathForm.path.test(url.pathname))
+            throw new Error(`stable URL must use the canonical ${provider} path`);
+        return url.toString();
+    }
+    const approved = PROVIDER_HOSTS[provider.toLowerCase()];
+    if (!approved || !approved.includes(url.hostname.toLowerCase()))
+        throw new Error(`stable URL must use an approved host for ${provider}`);
+    return url.toString();
+}
+export function isValidLinkedinUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && (url.hostname === "linkedin.com" || url.hostname.endsWith(".linkedin.com"));
+    }
+    catch {
+        return false;
+    }
+}
+const EMAIL_SHAPE = /[\w.+-]+@[\w-]+\.[\w.-]+/;
+// Domains where the mailbox says nothing about the company. Deriving "Gmail"
+// as an employer is noise, not a candidate.
+const FREE_MAIL_DOMAINS = new Set([
+    "gmail.com", "googlemail.com", "yahoo.com", "ymail.com", "outlook.com", "hotmail.com",
+    "live.com", "msn.com", "icloud.com", "me.com", "mac.com", "aol.com", "proton.me",
+    "protonmail.com", "pm.me", "fastmail.com", "hey.com", "gmx.com", "zoho.com",
+]);
+// R-004: the email-privacy rule. The company is derived from the DOMAIN and the
+// address itself is discarded here, before any hint exists — a raw attendee
+// email must never persist in a committed file. Free-mail domains yield null.
+export function companyFromEmailDomain(email) {
+    const at = email.lastIndexOf("@");
+    if (at < 1)
+        return null;
+    const domain = email.slice(at + 1).trim().toLowerCase();
+    if (!domain || FREE_MAIL_DOMAINS.has(domain))
+        return null;
+    const base = domain.split(".")[0];
+    if (!base || /^\d+$/.test(base))
+        return null;
+    return base.charAt(0).toUpperCase() + base.slice(1);
+}
+// Parses a provider display label. "Chris Exampleton from Exampleton Brothers"
+// yields the name AND the company; a plain capitalized person name yields the
+// name; an email-shaped or unrecognized label yields nothing — conservative on
+// purpose, because every hint is a suggestion a person will read.
+const DISPLAY_NAME = /^([A-Z][a-zA-Z'’.-]*(?: [A-Z][a-zA-Z'’.-]*)+)$/;
+const DISPLAY_NAME_WITH_COMPANY = /^([A-Z][a-zA-Z'’.-]*(?: [A-Z][a-zA-Z'’.-]*)+)\s+(?:from|of|at)\s+([A-Z][A-Za-z0-9&.'’-]*(?: [A-Z][A-Za-z0-9&.'’-]*){0,3})$/;
+export function contactHintsFromDisplayLabel(label, source) {
+    const trimmed = label.trim();
+    if (!trimmed || EMAIL_SHAPE.test(trimmed))
+        return [];
+    const withCompany = DISPLAY_NAME_WITH_COMPANY.exec(trimmed);
+    if (withCompany) {
+        return [
+            { field: "full_name", value: withCompany[1], source },
+            { field: "company", value: withCompany[2].replace(/[.,;:]$/, ""), source },
+        ];
+    }
+    const plain = DISPLAY_NAME.exec(trimmed);
+    return plain ? [{ field: "full_name", value: plain[1], source }] : [];
+}
+export function dedupeContactHints(hints) {
+    const seen = new Set();
+    const out = [];
+    for (const hint of hints) {
+        const key = `${hint.field}:${hint.value.trim().toLowerCase()}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(hint);
+    }
+    return out;
+}
+export function adapterCapabilityState(capabilities) {
+    if (!capabilities.list_sessions || !capabilities.open_transcript)
+        return "needs_provider_connector";
+    if (!capabilities.stable_link || !capabilities.timestamps)
+        return "ready_with_coverage_caveat";
+    return "ready";
+}
+export function validateNormalizedSession(session) {
+    const errors = [];
+    if (session.schema_version !== "0.1")
+        errors.push("schema_version must be 0.1");
+    if (!session.provider?.trim())
+        errors.push("provider is required");
+    if (!session.connection_alias?.trim())
+        errors.push("connection_alias is required");
+    if (!session.runtime_handle?.trim())
+        errors.push("runtime_handle is required in private runtime memory");
+    if (session.completion_state !== "completed")
+        errors.push("completion_state must be completed");
+    if (!session.title?.trim())
+        errors.push("title is required");
+    if (!Array.isArray(session.participants))
+        errors.push("participants must be an array");
+    if (!Number.isFinite(Date.parse(session.completed_at)))
+        errors.push("completed_at must be an ISO timestamp");
+    if (session.stable_url) {
+        try {
+            sanitizeDiscoveryStableUrl(session.provider, session.stable_url);
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : "invalid stable URL");
+        }
+    }
+    if (session.contact_hints !== undefined) {
+        if (!Array.isArray(session.contact_hints))
+            errors.push("contact_hints must be an array");
+        else {
+            for (const [index, hint] of session.contact_hints.entries()) {
+                const label = `contact hint ${index + 1}`;
+                if (!hint || typeof hint !== "object" || Array.isArray(hint)) {
+                    errors.push(`${label} must be an object`);
+                    continue;
+                }
+                if (hint.field !== "full_name" && hint.field !== "company" && hint.field !== "title" && hint.field !== "linkedin")
+                    errors.push(`${label}: invalid field`);
+                if (typeof hint.value !== "string" || !hint.value.trim())
+                    errors.push(`${label}: value is required`);
+                else if (EMAIL_SHAPE.test(hint.value))
+                    errors.push(`${label}: value must not contain an email address — derive the company from the domain and keep the address out`);
+                else if (hint.field === "linkedin" && !isValidLinkedinUrl(hint.value))
+                    errors.push(`${label}: linkedin value must be an https linkedin.com URL`);
+                if (typeof hint.source !== "string" || !hint.source.trim())
+                    errors.push(`${label}: source is required`);
+            }
+        }
+    }
+    return errors;
+}
+const NORMALIZED_SESSION_KEYS = new Set([
+    "schema_version",
+    "provider",
+    "connection_alias",
+    "runtime_handle",
+    "completed_at",
+    "completion_state",
+    "title",
+    "participants",
+    "stable_url",
+    "capabilities",
+    "access",
+    "contact_hints",
+]);
+const CAPABILITY_KEYS = new Set(["list_sessions", "open_transcript", "stable_link", "timestamps"]);
+const CONTACT_HINT_KEYS = new Set(["field", "value", "source"]);
+export function assertNormalizedSessionShape(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("session metadata must be an object");
+    const session = value;
+    for (const key of Object.keys(session)) {
+        if (!NORMALIZED_SESSION_KEYS.has(key))
+            throw new Error(`session metadata contains forbidden or unknown field ${key}`);
+    }
+    if (!session.capabilities || typeof session.capabilities !== "object" || Array.isArray(session.capabilities))
+        throw new Error("session capabilities must be an object");
+    for (const key of Object.keys(session.capabilities)) {
+        if (!CAPABILITY_KEYS.has(key))
+            throw new Error(`session capabilities contain unknown field ${key}`);
+    }
+    if (session.contact_hints !== undefined) {
+        if (!Array.isArray(session.contact_hints))
+            throw new Error("session contact_hints must be an array");
+        for (const hint of session.contact_hints) {
+            if (!hint || typeof hint !== "object" || Array.isArray(hint))
+                throw new Error("session contact hints must be objects");
+            for (const key of Object.keys(hint)) {
+                if (!CONTACT_HINT_KEYS.has(key))
+                    throw new Error(`session contact hint contains forbidden or unknown field ${key}`);
+            }
+        }
+    }
+    const errors = validateNormalizedSession(session);
+    if (errors.length)
+        throw new Error(`invalid normalized session metadata: ${errors.join("; ")}`);
+}

package/dist-public/src/discoverySync.d.ts

@@ -0,0 +1,52 @@
+export type DiscoverySyncAction = "list_metadata" | "match" | "open_authorized_transcript" | "apply_sanitized_evidence";
+export type DiscoverySyncLane = {
+    lane_id: string;
+    kind: "study" | "inbox";
+    provider: string;
+    connection_alias: string;
+    study_id?: string;
+    scope_id?: string;
+    lifecycle: string;
+    allowed_actions: DiscoverySyncAction[];
+};
+export type DiscoverySyncPlan = {
+    schema_version: "0.1";
+    generated_at: string;
+    lanes: DiscoverySyncLane[];
+    errors: string[];
+    connector_reads: 0;
+};
+export declare function planDiscoverySync(root: string, now: string): DiscoverySyncPlan;
+export type DiscoveryLaneResult = {
+    lane_id: string;
+    provider: string;
+    status: "clean_no_op" | "needs_review" | "blocked" | "provider_failure";
+    writes: string[];
+    error_code?: string;
+};
+export type DiscoverySyncAggregate = {
+    status: "clean_no_op" | "ok" | "needs_review" | "invalid";
+    writes: string[];
+    errors: Array<{
+        lane_id: string;
+        provider: string;
+        code: string;
+    }>;
+    coverage: {
+        lanes: number;
+        succeeded: number;
+        failed: number;
+        partial_failure: boolean;
+    };
+};
+export declare function aggregateDiscoverySync(results: DiscoveryLaneResult[]): DiscoverySyncAggregate;
+export type RepoSnapshot = {
+    root: string;
+    files: Record<string, string>;
+};
+export declare function snapshotDiscoverySyncPaths(root: string): RepoSnapshot;
+export declare function validateDiscoverySyncWrites(before: RepoSnapshot, after: RepoSnapshot): {
+    ok: boolean;
+    changed: string[];
+    forbidden: string[];
+};

package/dist-public/src/discoverySync.js

@@ -0,0 +1,151 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { approvalStates, sourceKey } from "./sourceIngress.js";
+import { loadDiscoveryRun } from "./discoveryArtifacts.js";
+import { parse } from "./vendorYaml.js";
+const TERMINAL = new Set(["complete", "revoked"]);
+function actionsFor(lifecycle) {
+    if (lifecycle === "awaiting_interview" || lifecycle === "draft" || lifecycle === "needs_review")
+        return [];
+    if (lifecycle === "ready_to_synthesize")
+        return ["open_authorized_transcript", "apply_sanitized_evidence"];
+    return ["list_metadata", "match", "open_authorized_transcript", "apply_sanitized_evidence"];
+}
+function hasCustomerSelector(scope) {
+    // call_owners is a gong selector kind (gong-discovery-connector-v0 R-004)
+    // and organizations/brands are zendesk kinds (zendesk-discovery-connector-v0
+    // R-004); other providers leave them unset, so this stays the generic inbox
+    // rule.
+    return [scope.participant_allowlist, scope.domain_allowlist, scope.title_tokens, scope.call_owners, scope.organizations, scope.brands]
+        .some((values) => Array.isArray(values) && values.some((value) => typeof value === "string" && value.trim()));
+}
+function scopeApprovalAllows(inboxDir, scope) {
+    if (!scope.provider || !scope.connection_alias || !scope.scope_id)
+        return false;
+    const approval = approvalStates(inboxDir).get(sourceKey({ provider: scope.provider, connection_id: scope.connection_alias }));
+    // Approvals accumulate per scope (#528): any approved scope on the connection
+    // may cover this inbox scope; scopes arrive trimmed from approvalStates.
+    return (approval?.state === "approved" &&
+        approval.scopes.some((approved) => approved === "*" || approved === scope.scope_id || approved === `scope:${scope.scope_id}`));
+}
+export function planDiscoverySync(root, now) {
+    const lanes = [];
+    const errors = [];
+    const discoveryRoot = path.join(root, "discovery");
+    if (!existsSync(discoveryRoot))
+        return { schema_version: "0.1", generated_at: now, lanes, errors: ["discovery/ is missing"], connector_reads: 0 };
+    for (const entry of readdirSync(discoveryRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory() || entry.name === "inbox")
+            continue;
+        const dir = path.join(discoveryRoot, entry.name);
+        try {
+            const run = loadDiscoveryRun(dir);
+            if (TERMINAL.has(run.state))
+                continue;
+            lanes.push({
+                lane_id: `study:${run.study_id}`,
+                kind: "study",
+                provider: run.source.provider,
+                connection_alias: run.source.connection_alias,
+                study_id: run.study_id,
+                lifecycle: run.state,
+                allowed_actions: actionsFor(run.state),
+            });
+        }
+        catch {
+            errors.push(`${entry.name}: invalid discovery run`);
+        }
+    }
+    const inboxDir = path.join(discoveryRoot, "inbox");
+    const scopePath = path.join(inboxDir, "scope.yaml");
+    if (existsSync(scopePath)) {
+        let scopes = [];
+        try {
+            const doc = parse(readFileSync(scopePath, "utf8"));
+            scopes = Array.isArray(doc.scopes) ? doc.scopes : [];
+        }
+        catch {
+            errors.push("inbox/scope.yaml is invalid");
+        }
+        for (const scope of scopes) {
+            if (scope.state !== "approved")
+                continue;
+            if (!hasCustomerSelector(scope)) {
+                errors.push(`${scope.scope_id ?? "inbox scope"}: approved ingestion requires at least one customer selector`);
+                continue;
+            }
+            if (!scope.time_window?.start || !scope.time_window?.end) {
+                errors.push(`${scope.scope_id ?? "inbox scope"}: bounded time window is required`);
+                continue;
+            }
+            if (!scopeApprovalAllows(inboxDir, scope)) {
+                errors.push(`${scope.scope_id ?? "inbox scope"}: matching source approval is missing`);
+                continue;
+            }
+            if (!scope.scope_id || !scope.provider || !scope.connection_alias) {
+                errors.push("inbox scope identity is incomplete");
+                continue;
+            }
+            lanes.push({
+                lane_id: `inbox:${scope.scope_id}`,
+                kind: "inbox",
+                provider: scope.provider,
+                connection_alias: scope.connection_alias,
+                scope_id: scope.scope_id,
+                lifecycle: "approved",
+                allowed_actions: ["list_metadata", "match", "open_authorized_transcript", "apply_sanitized_evidence"],
+            });
+        }
+    }
+    return { schema_version: "0.1", generated_at: now, lanes, errors, connector_reads: 0 };
+}
+export function aggregateDiscoverySync(results) {
+    const errors = results
+        .filter((entry) => entry.status === "provider_failure" || entry.status === "blocked")
+        .map((entry) => ({ lane_id: entry.lane_id, provider: entry.provider, code: entry.error_code ?? "E_DISCOVERY_VALIDATION" }));
+    const writes = [...new Set(results.flatMap((entry) => entry.writes))].sort();
+    const succeeded = results.length - errors.length;
+    const status = results.length === 0
+        ? "clean_no_op"
+        : results.some((entry) => entry.status === "needs_review")
+            ? "needs_review"
+            : errors.length === results.length
+                ? "invalid"
+                : writes.length
+                    ? "ok"
+                    : "clean_no_op";
+    return { status, writes, errors, coverage: { lanes: results.length, succeeded, failed: errors.length, partial_failure: errors.length > 0 && succeeded > 0 } };
+}
+function snapshotFiles(root, dir = root) {
+    const files = {};
+    if (!existsSync(dir))
+        return files;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if ([".git", "node_modules", "dist"].includes(entry.name))
+            continue;
+        const full = path.join(dir, entry.name);
+        const relative = path.relative(root, full).split(path.sep).join("/");
+        if (entry.isDirectory()) {
+            if (relative === ".foo" || relative.startsWith(".foo/")) {
+                if (relative !== ".foo" && relative !== ".foo/discovery" && !relative.startsWith(".foo/discovery/"))
+                    continue;
+            }
+            Object.assign(files, snapshotFiles(root, full));
+        }
+        else if (entry.isFile()) {
+            files[relative] = readFileSync(full, "utf8");
+        }
+    }
+    return files;
+}
+export function snapshotDiscoverySyncPaths(root) {
+    return { root: path.resolve(root), files: snapshotFiles(path.resolve(root)) };
+}
+export function validateDiscoverySyncWrites(before, after) {
+    if (before.root !== after.root)
+        return { ok: false, changed: [], forbidden: ["snapshot roots differ"] };
+    const paths = new Set([...Object.keys(before.files), ...Object.keys(after.files)]);
+    const changed = [...paths].filter((file) => before.files[file] !== after.files[file]).sort();
+    const forbidden = changed.filter((file) => !file.startsWith("discovery/") && !file.startsWith(".foo/discovery/"));
+    return { ok: forbidden.length === 0, changed, forbidden };
+}

package/dist-public/src/discoverySynthesis.d.ts

@@ -0,0 +1,57 @@
+import { type DiscoveryEvidenceEnvelope, type DiscoveryLane } from "./discoveryEvidence.js";
+export type SynthesisTransport = (request: {
+    model: string;
+    system: string;
+    user: string;
+    max_tokens: number;
+}) => Promise<{
+    text: string;
+    stop_reason?: string;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}>;
+export type SynthesisInput = {
+    target_id: string;
+    lane: DiscoveryLane;
+    source: {
+        provider: string;
+        stable_url?: string;
+        source_fingerprint: string;
+        completed_at: string;
+        locator_capability: "timestamp" | "section" | "none";
+    };
+    title: string;
+    hypotheses: Array<{
+        id: string;
+        text: string;
+    }>;
+    transcript_text: string;
+    transcript_complete: boolean;
+    caveats?: string[];
+};
+export type SynthesisResult = {
+    envelope: DiscoveryEvidenceEnvelope;
+    model: string;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+};
+export declare const SYNTHESIS_MAX_OUTPUT_TOKENS = 8000;
+export declare function defaultSynthesisModel(env?: NodeJS.ProcessEnv): string;
+export declare function synthesisCredentialPresent(env?: NodeJS.ProcessEnv): boolean;
+export declare const SYNTHESIS_SYSTEM_PROMPT: string;
+export declare function synthesisUserMessage(input: SynthesisInput): string;
+export declare function anthropicSynthesisTransport(deps?: {
+    fetchImpl?: typeof globalThis.fetch;
+    env?: NodeJS.ProcessEnv;
+}): SynthesisTransport;
+export declare function extractSynthesisJsonObject(text: string): Record<string, unknown>;
+export declare function constructEnvelopeFromSynthesis(input: SynthesisInput, raw: Record<string, unknown>): DiscoveryEvidenceEnvelope;
+export declare function buildEnvelopeFromSynthesis(input: SynthesisInput, raw: Record<string, unknown>): DiscoveryEvidenceEnvelope;
+export declare function synthesizeDiscoveryEnvelope(input: SynthesisInput, options: {
+    model: string;
+    transport: SynthesisTransport;
+}): Promise<SynthesisResult>;