productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/discoveryArtifacts.js

@@ -0,0 +1,467 @@
+import { appendFileSync, existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parse, stringify } from "./vendorYaml.js";
+import { providerLinkForm, sanitizeDiscoveryStableUrl } from "./discoverySources.js";
+export const DISCOVERY_SCHEMA_VERSION = "0.1";
+const LIFECYCLES = new Set([
+    "draft",
+    "awaiting_interview",
+    "awaiting_match",
+    "ambiguous_match",
+    "needs_source_approval",
+    "needs_provider_access",
+    "needs_provider_connector",
+    "needs_research_proof",
+    "ready_to_synthesize",
+    "needs_review",
+    "complete",
+    "revoked",
+]);
+const ALLOWED_TRANSITIONS = {
+    draft: ["awaiting_interview", "revoked"],
+    awaiting_interview: ["awaiting_match", "revoked"],
+    awaiting_match: ["ambiguous_match", "needs_source_approval", "needs_provider_access", "needs_provider_connector", "needs_research_proof", "ready_to_synthesize", "revoked"],
+    ambiguous_match: ["awaiting_match", "needs_source_approval", "needs_provider_access", "needs_provider_connector", "needs_research_proof", "ready_to_synthesize", "revoked"],
+    needs_source_approval: ["awaiting_match", "ambiguous_match", "needs_provider_access", "needs_provider_connector", "needs_research_proof", "ready_to_synthesize", "revoked"],
+    needs_provider_access: ["awaiting_match", "ambiguous_match", "needs_source_approval", "needs_provider_connector", "needs_research_proof", "ready_to_synthesize", "revoked"],
+    needs_provider_connector: ["awaiting_match", "ambiguous_match", "needs_source_approval", "needs_provider_access", "needs_research_proof", "ready_to_synthesize", "revoked"],
+    needs_research_proof: ["awaiting_match", "ambiguous_match", "needs_source_approval", "needs_provider_access", "needs_provider_connector", "ready_to_synthesize", "revoked"],
+    ready_to_synthesize: ["needs_review", "needs_provider_access", "needs_research_proof", "revoked"],
+    needs_review: ["complete", "awaiting_match", "revoked"],
+    complete: ["revoked"],
+    revoked: [],
+};
+const FORBIDDEN_PRIVATE_KEYS = new Set([
+    "runtime_handle",
+    "session_handle",
+    "meeting_id",
+    "connector_receipt",
+    "transcript",
+    "raw_transcript",
+    "raw_content",
+    "turns",
+    "utterances",
+]);
+const PROVENANCE = new Set(["approved-context", "agent-inference", "legacy-untrusted"]);
+const PROPOSAL_STATES = new Set(["draft", "needs_review", "promoted", "dismissed"]);
+function readYaml(file) {
+    return parse(readFileSync(file, "utf8"));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function walkPrivateKeys(value, at, errors) {
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => walkPrivateKeys(entry, `${at}[${index}]`, errors));
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    for (const [key, entry] of Object.entries(value)) {
+        if (FORBIDDEN_PRIVATE_KEYS.has(key.toLowerCase()))
+            errors.push(`${at}: forbidden private field ${key}`);
+        walkPrivateKeys(entry, `${at}.${key}`, errors);
+    }
+}
+function validateStableUrl(value, provider, at, errors) {
+    if (value === null || value === undefined || value === "")
+        return;
+    if (typeof value !== "string") {
+        errors.push(`${at}: stable_url must be a string or null`);
+        return;
+    }
+    // A provider with a declared canonical link form (gong-discovery-connector-v0
+    // R-006) is judged by that single form — the shared sanitizer is the only
+    // authority for it, so the two validators cannot drift for such providers.
+    if (providerLinkForm(provider)) {
+        try {
+            sanitizeDiscoveryStableUrl(provider, value);
+        }
+        catch (error) {
+            errors.push(`${at}: ${error instanceof Error ? error.message : "stable_url is invalid"}`);
+        }
+        return;
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        errors.push(`${at}: stable_url is invalid`);
+        return;
+    }
+    if (parsed.protocol !== "https:")
+        errors.push(`${at}: stable_url must use HTTPS`);
+    if (parsed.search)
+        errors.push(`${at}: stable_url must not contain a query string`);
+    if (parsed.hash)
+        errors.push(`${at}: stable_url must not contain a fragment`);
+    // Keep in lockstep with PROVIDER_HOSTS in discoverySources.ts (notes.granola.ai
+    // is Granola's share-link host — the divergence of these two lists refused an
+    // owner-approved ingestion once already; consolidation is a recorded follow-up).
+    const hosts = { granola: ["app.granola.ai", "granola.ai", "notes.granola.ai"] };
+    const approved = hosts[provider.toLowerCase()];
+    if (approved && !approved.includes(parsed.hostname.toLowerCase()))
+        errors.push(`${at}: stable_url host is not approved for ${provider}`);
+}
+export function loadDiscoveryRun(studyDir) {
+    const file = path.join(studyDir, "run.yaml");
+    if (!existsSync(file))
+        throw new Error(`missing discovery run: ${file}`);
+    return readYaml(file);
+}
+function validateRun(studyDir, errors) {
+    const required = ["run.yaml", "study.md", "findings.yaml", "proposals.yaml", "report.md", "events.jsonl"];
+    for (const name of required)
+        if (!existsSync(path.join(studyDir, name)))
+            errors.push(`${path.basename(studyDir)}: missing ${name}`);
+    if (!existsSync(path.join(studyDir, "run.yaml")))
+        return;
+    let run;
+    try {
+        run = readYaml(path.join(studyDir, "run.yaml"));
+    }
+    catch {
+        errors.push(`${path.basename(studyDir)}: run.yaml is not valid YAML`);
+        return;
+    }
+    walkPrivateKeys(run, `${path.basename(studyDir)}/run.yaml`, errors);
+    if (!isRecord(run)) {
+        errors.push(`${path.basename(studyDir)}: run.yaml must be an object`);
+        return;
+    }
+    if (run.schema_version !== DISCOVERY_SCHEMA_VERSION)
+        errors.push(`${path.basename(studyDir)}: schema_version must be 0.1`);
+    if (typeof run.study_id !== "string" || !/^study_[a-z0-9_]+$/.test(run.study_id))
+        errors.push(`${path.basename(studyDir)}: invalid study_id`);
+    if (!LIFECYCLES.has(run.state))
+        errors.push(`${path.basename(studyDir)}: invalid lifecycle state`);
+    if (run.lane !== "study_linked")
+        errors.push(`${path.basename(studyDir)}: study lane must be study_linked`);
+    if (!PROVENANCE.has(String(run.provenance)))
+        errors.push(`${path.basename(studyDir)}: invalid run provenance`);
+    const target = isRecord(run.target) ? run.target : {};
+    if (!PROVENANCE.has(String(target.provenance)))
+        errors.push(`${path.basename(studyDir)}: invalid target provenance`);
+    const source = isRecord(run.source) ? run.source : {};
+    const provider = typeof source.provider === "string" ? source.provider : "";
+    validateStableUrl(source.stable_url, provider, `${path.basename(studyDir)}/run.yaml`, errors);
+    validateDerivedArtifacts(studyDir, provider, errors);
+}
+function validateDerivedArtifacts(dir, provider, errors) {
+    const label = path.basename(dir);
+    const findingsPath = path.join(dir, "findings.yaml");
+    const proposalsPath = path.join(dir, "proposals.yaml");
+    const findingIds = new Set();
+    if (existsSync(findingsPath)) {
+        try {
+            const doc = readYaml(findingsPath);
+            walkPrivateKeys(doc, `${label}/findings.yaml`, errors);
+            if (!isRecord(doc) || doc.schema_version !== DISCOVERY_SCHEMA_VERSION || !Array.isArray(doc.findings)) {
+                errors.push(`${label}/findings.yaml must contain schema_version 0.1 and findings[]`);
+            }
+            else {
+                for (const [index, raw] of doc.findings.entries()) {
+                    if (!isRecord(raw)) {
+                        errors.push(`${label}/findings.yaml finding ${index + 1} must be an object`);
+                        continue;
+                    }
+                    if (typeof raw.finding_id !== "string" || !raw.finding_id.trim())
+                        errors.push(`${label}/findings.yaml finding ${index + 1}: finding_id is required`);
+                    else if (findingIds.has(raw.finding_id))
+                        errors.push(`${label}/findings.yaml finding ${index + 1}: duplicate finding_id ${raw.finding_id}`);
+                    else
+                        findingIds.add(raw.finding_id);
+                    if (raw.lane !== undefined && raw.lane !== "study_linked" && raw.lane !== "unassigned_call_evidence")
+                        errors.push(`${label}/findings.yaml finding ${index + 1}: invalid lane`);
+                    if (raw.source_fingerprint !== undefined && (typeof raw.source_fingerprint !== "string" || !/^sha256:[a-f0-9]{64}$/i.test(raw.source_fingerprint)))
+                        errors.push(`${label}/findings.yaml finding ${index + 1}: invalid source_fingerprint`);
+                    const sourceProvider = typeof raw.source_provider === "string" ? raw.source_provider : provider;
+                    validateStableUrl(raw.source_url, sourceProvider, `${label}/findings.yaml finding ${index + 1} source_url`, errors);
+                }
+            }
+        }
+        catch {
+            errors.push(`${label}/findings.yaml is not valid YAML`);
+        }
+    }
+    if (existsSync(proposalsPath)) {
+        try {
+            const doc = readYaml(proposalsPath);
+            walkPrivateKeys(doc, `${label}/proposals.yaml`, errors);
+            if (!isRecord(doc) || doc.schema_version !== DISCOVERY_SCHEMA_VERSION || !Array.isArray(doc.proposals)) {
+                errors.push(`${label}/proposals.yaml must contain schema_version 0.1 and proposals[]`);
+            }
+            else {
+                const proposalIds = new Set();
+                for (const [index, raw] of doc.proposals.entries()) {
+                    if (!isRecord(raw)) {
+                        errors.push(`${label}/proposals.yaml proposal ${index + 1} must be an object`);
+                        continue;
+                    }
+                    if (typeof raw.proposal_id !== "string" || !raw.proposal_id.trim())
+                        errors.push(`${label}/proposals.yaml proposal ${index + 1}: proposal_id is required`);
+                    else if (proposalIds.has(raw.proposal_id))
+                        errors.push(`${label}/proposals.yaml proposal ${index + 1}: duplicate proposal_id ${raw.proposal_id}`);
+                    else
+                        proposalIds.add(raw.proposal_id);
+                    if (!PROPOSAL_STATES.has(String(raw.state)))
+                        errors.push(`${label}/proposals.yaml proposal ${index + 1}: invalid state`);
+                    const refs = Array.isArray(raw.source_finding_ids) ? raw.source_finding_ids : [];
+                    for (const ref of refs)
+                        if (typeof ref !== "string" || !findingIds.has(ref))
+                            errors.push(`${label}/proposals.yaml proposal ${index + 1}: ${String(ref)} references an unknown finding`);
+                }
+            }
+        }
+        catch {
+            errors.push(`${label}/proposals.yaml is not valid YAML`);
+        }
+    }
+    const eventsPath = path.join(dir, "events.jsonl");
+    if (existsSync(eventsPath)) {
+        for (const [index, line] of readFileSync(eventsPath, "utf8").split("\n").entries()) {
+            if (!line.trim())
+                continue;
+            try {
+                walkPrivateKeys(JSON.parse(line), `${label}/events.jsonl line ${index + 1}`, errors);
+            }
+            catch {
+                errors.push(`${label}/events.jsonl line ${index + 1} is not valid JSON`);
+            }
+        }
+    }
+}
+function validateInbox(inboxDir, errors) {
+    for (const name of ["scope.yaml", "findings.yaml", "proposals.yaml", "events.jsonl"]) {
+        if (!existsSync(path.join(inboxDir, name)))
+            errors.push(`inbox: missing ${name}`);
+    }
+    const scopePath = path.join(inboxDir, "scope.yaml");
+    if (!existsSync(scopePath))
+        return;
+    let doc;
+    try {
+        doc = readYaml(scopePath);
+    }
+    catch {
+        errors.push("inbox/scope.yaml is not valid YAML");
+        return;
+    }
+    walkPrivateKeys(doc, "inbox/scope.yaml", errors);
+    if (!isRecord(doc) || doc.schema_version !== DISCOVERY_SCHEMA_VERSION || !Array.isArray(doc.scopes)) {
+        errors.push("inbox/scope.yaml must contain schema_version 0.1 and scopes[]");
+        return;
+    }
+    const scopeIds = new Set();
+    for (const [index, raw] of doc.scopes.entries()) {
+        if (!isRecord(raw)) {
+            errors.push(`inbox scope ${index + 1} must be an object`);
+            continue;
+        }
+        if (typeof raw.scope_id !== "string" || !/^[a-z0-9_]+$/.test(raw.scope_id))
+            errors.push(`inbox scope ${index + 1}: invalid scope_id`);
+        else if (scopeIds.has(raw.scope_id))
+            errors.push(`inbox scope ${index + 1}: duplicate scope_id ${raw.scope_id}`);
+        else
+            scopeIds.add(raw.scope_id);
+        if (raw.state !== "draft" && raw.state !== "approved" && raw.state !== "revoked")
+            errors.push(`inbox scope ${index + 1}: invalid state`);
+        if (raw.state === "approved" && (!raw.approved_by || !raw.approved_at))
+            errors.push(`inbox scope ${index + 1}: approved scope requires attribution`);
+        // At least one customer selector; call_owners is a gong kind
+        // (gong-discovery-connector-v0 R-004) and is empty/absent elsewhere.
+        const selectors = [raw.participant_allowlist, raw.domain_allowlist, raw.title_tokens, raw.call_owners];
+        if (!selectors.some((entry) => Array.isArray(entry) && entry.some((item) => typeof item === "string" && item.trim()))) {
+            errors.push(`inbox scope ${index + 1}: approved ingestion requires at least one customer selector`);
+        }
+        if (!isRecord(raw.time_window) || !raw.time_window.start || !raw.time_window.end)
+            errors.push(`inbox scope ${index + 1}: time_window requires start and end`);
+        else {
+            const start = Date.parse(String(raw.time_window.start));
+            const end = Date.parse(String(raw.time_window.end));
+            if (!Number.isFinite(start) || !Number.isFinite(end) || start > end)
+                errors.push(`inbox scope ${index + 1}: time_window must contain valid ordered timestamps`);
+        }
+    }
+    validateDerivedArtifacts(inboxDir, "", errors);
+    // Contact cards (discovery-insight-ties-v0 R-007): optional, human-corrected
+    // identity per scope. Absent is valid; present must be well-formed.
+    const contactsPath = path.join(inboxDir, "contacts.yaml");
+    if (existsSync(contactsPath)) {
+        let contactsDoc;
+        try {
+            contactsDoc = readYaml(contactsPath);
+        }
+        catch {
+            errors.push("inbox/contacts.yaml is not valid YAML");
+            return;
+        }
+        walkPrivateKeys(contactsDoc, "inbox/contacts.yaml", errors);
+        if (!isRecord(contactsDoc) || contactsDoc.schema_version !== DISCOVERY_SCHEMA_VERSION || !Array.isArray(contactsDoc.contacts)) {
+            errors.push("inbox/contacts.yaml must contain schema_version 0.1 and contacts[]");
+            return;
+        }
+        const contactScopeIds = new Set();
+        for (const [index, raw] of contactsDoc.contacts.entries()) {
+            if (!isRecord(raw)) {
+                errors.push(`inbox contact ${index + 1} must be an object`);
+                continue;
+            }
+            if (typeof raw.scope_id !== "string" || !scopeIds.has(raw.scope_id))
+                errors.push(`inbox contact ${index + 1}: scope_id must name a known inbox scope`);
+            else if (contactScopeIds.has(raw.scope_id))
+                errors.push(`inbox contact ${index + 1}: duplicate scope_id ${raw.scope_id}`);
+            else
+                contactScopeIds.add(raw.scope_id);
+            for (const field of ["full_name", "linkedin", "company", "title"]) {
+                if (raw[field] !== null && raw[field] !== undefined && typeof raw[field] !== "string")
+                    errors.push(`inbox contact ${index + 1}: ${field} must be a string or null`);
+            }
+            if (typeof raw.linkedin === "string" && raw.linkedin && !isLinkedinUrl(raw.linkedin)) {
+                errors.push(`inbox contact ${index + 1}: linkedin must be an https linkedin.com URL`);
+            }
+            // Candidate layer (discovery-contact-capture-v0 R-002/R-004): inferred
+            // suggestions with provenance, beneath the human-confirmed fields. A
+            // candidate value carrying an email or phone number is a privacy leak,
+            // not a candidate — the company is derived from the domain at ingest and
+            // the raw address must never reach this committed file.
+            if (raw.candidates !== undefined) {
+                if (!Array.isArray(raw.candidates)) {
+                    errors.push(`inbox contact ${index + 1}: candidates must be an array`);
+                    continue;
+                }
+                for (const [candidateIndex, candidate] of raw.candidates.entries()) {
+                    const label = `inbox contact ${index + 1} candidate ${candidateIndex + 1}`;
+                    if (!isRecord(candidate)) {
+                        errors.push(`${label} must be an object`);
+                        continue;
+                    }
+                    for (const key of Object.keys(candidate)) {
+                        if (!CONTACT_CANDIDATE_KEYS.has(key))
+                            errors.push(`${label}: unknown field ${key}`);
+                    }
+                    if (candidate.field !== "full_name" && candidate.field !== "company" && candidate.field !== "title" && candidate.field !== "linkedin")
+                        errors.push(`${label}: field must be full_name, company, title, or linkedin`);
+                    if (candidate.inferred !== true)
+                        errors.push(`${label}: candidates are always inferred: true — confirmed values live on the card fields`);
+                    if (typeof candidate.source !== "string" || !candidate.source.trim())
+                        errors.push(`${label}: source is required`);
+                    if (typeof candidate.value !== "string" || !candidate.value.trim())
+                        errors.push(`${label}: value is required`);
+                    else {
+                        if (CONTACT_EMAIL.test(candidate.value) || CONTACT_PHONE.test(candidate.value))
+                            errors.push(`${label}: value must not contain an email address or phone number`);
+                        if (candidate.field === "linkedin" && !isLinkedinUrl(candidate.value))
+                            errors.push(`${label}: linkedin value must be an https linkedin.com URL`);
+                    }
+                }
+            }
+        }
+    }
+}
+const CONTACT_CANDIDATE_KEYS = new Set(["field", "value", "inferred", "source"]);
+const CONTACT_EMAIL = /[\w.+-]+@[\w-]+\.[\w.-]+/;
+const CONTACT_PHONE = /\+?\d[\d\s().-]{7,}\d/;
+function isLinkedinUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && (url.hostname === "linkedin.com" || url.hostname.endsWith(".linkedin.com"));
+    }
+    catch {
+        return false;
+    }
+}
+export function validateDiscoveryPath(root, target) {
+    const discoveryRoot = path.resolve(root, target ?? "discovery");
+    const errors = [];
+    if (!existsSync(discoveryRoot))
+        return { ok: false, errors: [`discovery path not found: ${discoveryRoot}`], studies: 0, inbox: false };
+    const directRun = existsSync(path.join(discoveryRoot, "run.yaml"));
+    const studyDirs = directRun
+        ? [discoveryRoot]
+        : readdirSync(discoveryRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && entry.name !== "inbox")
+            .map((entry) => path.join(discoveryRoot, entry.name));
+    const studyIds = new Set();
+    for (const studyDir of studyDirs) {
+        validateRun(studyDir, errors);
+        try {
+            const studyId = loadDiscoveryRun(studyDir).study_id;
+            if (studyIds.has(studyId))
+                errors.push(`${path.basename(studyDir)}: duplicate study_id ${studyId}`);
+            else
+                studyIds.add(studyId);
+        }
+        catch {
+            continue;
+        }
+    }
+    const inboxDir = directRun ? "" : path.join(discoveryRoot, "inbox");
+    const inbox = Boolean(inboxDir && existsSync(inboxDir));
+    if (inbox)
+        validateInbox(inboxDir, errors);
+    return { ok: errors.length === 0, errors, studies: studyDirs.length, inbox };
+}
+export function locateStudy(root, studyId) {
+    const discoveryRoot = path.join(root, "discovery");
+    if (!existsSync(discoveryRoot))
+        return null;
+    for (const entry of readdirSync(discoveryRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name === "inbox")
+            continue;
+        const dir = path.join(discoveryRoot, entry.name);
+        try {
+            if (loadDiscoveryRun(dir).study_id === studyId)
+                return dir;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function repositoryRootForStudy(studyDir) {
+    return path.dirname(path.dirname(path.resolve(studyDir)));
+}
+export function transitionDiscoveryRun(studyDir, next, actor, now) {
+    if (!actor.id.trim())
+        throw new Error("discovery transition requires an attributed actor");
+    const run = loadDiscoveryRun(studyDir);
+    const prior = run.state;
+    if (!ALLOWED_TRANSITIONS[prior].includes(next))
+        throw new Error(`invalid discovery transition: ${prior} -> ${next}`);
+    if ((next === "complete" || next === "revoked") && actor.type !== "human")
+        throw new Error(`${next} is a human transition`);
+    run.state = next;
+    run.updated_at = now;
+    const runPath = path.join(studyDir, "run.yaml");
+    writeFileSync(runPath, stringify(run));
+    const event = {
+        specversion: "1.0",
+        id: `evt_discovery_${run.study_id}_${next}_${Date.parse(now)}`,
+        source: "agent://foo/discovery",
+        type: "com.adaptivespec.discovery.state_changed",
+        subject: `study:${run.study_id}`,
+        time: now,
+        actor,
+        data: { from: prior, to: next },
+    };
+    // The event intentionally carries only lifecycle provenance, never evidence.
+    appendFileSync(path.join(studyDir, "events.jsonl"), `${JSON.stringify(event)}\n`);
+    const root = repositoryRootForStudy(studyDir);
+    return [runPath, path.join(studyDir, "events.jsonl")].map((file) => ({ path: path.relative(root, file).split(path.sep).join("/"), action: "updated" }));
+}
+export function classifyDiscoveryCandidate(filePath, text) {
+    const normalizedPath = filePath.toLowerCase();
+    const normalizedText = text.toLowerCase();
+    if (normalizedPath.includes("/specs/") || normalizedPath.startsWith("specs/") || /product requirements|spec id/.test(normalizedText))
+        return "product-spec";
+    if (normalizedPath.includes("research/") || /research:|interview methods|method research/.test(normalizedText))
+        return "method-research";
+    if (/synthetic|rehearsal|mock interview/.test(normalizedText))
+        return "synthetic-rehearsal";
+    if (/customer interview|discovery call/.test(normalizedText) && /completed call|findings|evidence/.test(normalizedText))
+        return "real-study";
+    return "not-discovery";
+}

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

@@ -0,0 +1,127 @@
+import { type DiscoveryWrite } from "./discoveryArtifacts.js";
+export declare const DISCOVERY_COMMAND_SCHEMA_VERSION: "0.1";
+export type DiscoveryErrorCode = "E_DISCOVERY_SOURCE_APPROVAL" | "E_DISCOVERY_PROVIDER_ACCESS" | "E_DISCOVERY_PROVIDER_CONNECTOR" | "E_DISCOVERY_RESEARCH_PROOF" | "E_DISCOVERY_AMBIGUOUS_MATCH" | "E_DISCOVERY_INVALID_ENVELOPE" | "E_DISCOVERY_INVALID_TRANSITION" | "E_DISCOVERY_MANUAL_RESOLUTION" | "E_DISCOVERY_RECEIPT" | "E_DISCOVERY_VALIDATION";
+export type DiscoveryCommandStatus = "ok" | "clean_no_op" | "awaiting_match" | "ambiguous_match" | "needs_source_approval" | "needs_provider_access" | "needs_provider_connector" | "needs_research_proof" | "needs_review" | "needs_service_verification" | "invalid" | "budget_exhausted";
+export type DiscoveryCommandResult = {
+    schema_version: "0.1";
+    status: DiscoveryCommandStatus;
+    study_id?: string;
+    writes: DiscoveryWrite[];
+    errors: Array<{
+        code: DiscoveryErrorCode;
+        message: string;
+    }>;
+    handoff: string | null;
+    next_actions: string[];
+    coverage: Record<string, unknown>;
+};
+export type DiscoveryCommandOutcome = {
+    output: string;
+    exitCode: number;
+    result: DiscoveryCommandResult;
+};
+export declare function study(root: string, studyId: string): string;
+export type InboxScope = {
+    scope_id: string;
+    provider: string;
+    connection_alias: string;
+    time_window: {
+        start: string;
+        end: string;
+    };
+    participant_allowlist: string[];
+    domain_allowlist: string[];
+    title_tokens: string[];
+    call_owners?: string[];
+    organizations?: string[];
+    brands?: string[];
+    include_internal_only?: boolean;
+    labels?: string[];
+    channel_ids?: string[];
+    thread_ts?: string[];
+    folders?: string[];
+    state: "draft" | "approved" | "revoked";
+};
+export declare function isInboxTarget(targetId: string): boolean;
+export declare function inboxDir(root: string): string;
+export declare function ensureInboxScaffold(root: string): void;
+export declare function discoveryTargetDir(root: string, targetId: string): string;
+export declare function localTargetName(targetId: string): string;
+export declare function inboxScope(root: string, targetId: string): InboxScope;
+export type GongScopeSelectors = {
+    window: {
+        start?: string;
+        end?: string;
+    };
+    named_external_participants?: string[];
+    external_companies_or_domains?: string[];
+    title_tokens?: string[];
+    call_owners?: string[];
+};
+export declare function gongScopeValidationError(scope: GongScopeSelectors): string | null;
+export type ZendeskScopeSelectors = {
+    window: {
+        start?: string;
+        end?: string;
+    };
+    external_domains?: string[];
+    organizations?: string[];
+    brands?: string[];
+    include_internal_only?: boolean;
+};
+export declare function zendeskScopeValidationError(scope: ZendeskScopeSelectors): string | null;
+export type GmailScopeSelectors = {
+    window: {
+        start?: string;
+        end?: string;
+    };
+    labels?: string[];
+    external_domains?: string[];
+    external_names?: string[];
+    include_internal_only?: boolean;
+};
+export declare function gmailScopeValidationError(scope: GmailScopeSelectors): string | null;
+export type ZoomScopeSelectors = {
+    window: {
+        start?: string;
+        end?: string;
+    };
+    external_names?: string[];
+    external_domains?: string[];
+    title_tokens?: string[];
+    include_internal_only?: boolean;
+};
+export declare function zoomScopeValidationError(scope: ZoomScopeSelectors): string | null;
+export type TeamsScopeSelectors = {
+    window: {
+        start?: string;
+        end?: string;
+    };
+    named_external_participants?: string[];
+    external_companies_or_domains?: string[];
+    organizers?: string[];
+};
+export declare function teamsScopeValidationError(scope: TeamsScopeSelectors): string | null;
+export type OutlookScopeSelectors = {
+    window: {
+        start?: string;
+        end?: string;
+    };
+    folders?: string[];
+    external_domains?: string[];
+    external_names?: string[];
+    include_internal_only?: boolean;
+};
+export declare function outlookScopeValidationError(scope: OutlookScopeSelectors): string | null;
+export declare function localRoot(root: string): string;
+export declare function existingFingerprint(studyDir: string, fingerprint: string): boolean;
+export type InsightTie = {
+    type: "bug" | "spec" | "research" | "idea" | "study";
+    ref: string;
+    url: string | null;
+    by: string;
+    actor: "agent" | "human";
+    at: string;
+};
+export { isValidLinkedinUrl } from "./discoverySources.js";
+export declare function runDiscoveryCommand(root: string, args: string[], stdin?: string, now?: string): Promise<DiscoveryCommandOutcome>;