@world-engines/project-host 0.1.0-alpha.0

package/dist/authoring-ingestion.js

@@ -0,0 +1,410 @@
+import { sha256Hex } from "@world-engines/project-format";
+import { WORLD_FACT_EXTRACTION_RESULT_SCHEMA, createNaturalLanguageWorldOperations, decodeWorldFactExtractionResult, } from "@world-engines/tmw/natural-language-ingestion";
+import { INGESTION_SOURCE_CONTROL_KIND, ingestionFactEntityId, ingestionSourceMarkerId, ingestionSourceReconciliationReadIds, readIngestionSourceMarker, reconcileIngestionSource, } from "./ingestion-source-reconciliation.js";
+const EXTRACTION_JSON_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["facts"],
+    properties: {
+        facts: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: [
+                    "subject_label", "predicate", "object_type", "object_value_json", "confidence", "evidence_quote",
+                ],
+                properties: {
+                    subject_label: { type: "string", minLength: 1 },
+                    predicate: { type: "string", minLength: 1, pattern: "^[a-z][a-z0-9_]{0,63}$" },
+                    object_type: { type: "string", enum: ["string", "number", "boolean", "entity", "json"] },
+                    object_value_json: { type: "string", minLength: 1 },
+                    qualifiers_json: { type: "string" },
+                    confidence: { type: "number", minimum: 0, maximum: 1 },
+                    evidence_quote: { type: "string", minLength: 1 },
+                },
+            },
+        },
+    },
+});
+function record(value, code) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(code);
+    return value;
+}
+function exactKeys(value, expected, code) {
+    const actual = Object.keys(value).sort();
+    const sortedExpected = [...expected].sort();
+    if (actual.length !== sortedExpected.length || actual.some((key, index) => key !== sortedExpected[index]))
+        throw new Error(code);
+}
+const PROVIDER_FACT_KEYS = Object.freeze([
+    "subject_label", "predicate", "object_type", "object_value_json", "confidence", "evidence_quote",
+]);
+function parseJson(value, code) {
+    if (typeof value !== "string")
+        throw new Error(code);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(code);
+    }
+}
+function rejectionCode(error, fallback) {
+    const message = error instanceof Error ? error.message : fallback;
+    const stable = message
+        .replace(/^tmw_runtime_/u, "")
+        .replace(/world_fact_provider_\d+_/gu, "world_fact_provider_")
+        .replace(/world_fact_\d+_/gu, "world_fact_");
+    return /^[a-z0-9_]{1,160}$/u.test(stable) ? stable : fallback;
+}
+function rejectFact(diagnostics, error, fallback) {
+    diagnostics.rejectedFactCount += 1;
+    const code = rejectionCode(error, fallback);
+    diagnostics.rejectionReasons[code] = (diagnostics.rejectionReasons[code] ?? 0) + 1;
+}
+function normalizedProviderText(value, code) {
+    if (typeof value !== "string")
+        return value;
+    const normalized = value.trim().normalize("NFC");
+    if (normalized.length === 0 || normalized.includes("\0"))
+        throw new Error(code);
+    return normalized;
+}
+function normalizeEvidence(fact, chunkText, index) {
+    const quote = fact.evidence_quote;
+    if (typeof quote !== "string" || quote.length === 0)
+        throw new Error(`world_fact_${index}_evidence_invalid`);
+    const uniqueStart = chunkText.indexOf(quote);
+    if (uniqueStart < 0 || chunkText.lastIndexOf(quote) !== uniqueStart)
+        throw new Error(`world_fact_${index}_evidence_offset_unprovable`);
+    return { startOffset: uniqueStart, endOffset: uniqueStart + quote.length, quote };
+}
+async function stableEntityId(scopeId, label, code) {
+    const canonicalLabel = normalizedProviderText(label, code);
+    if (typeof canonicalLabel !== "string" || canonicalLabel.length > 512)
+        throw new Error(code);
+    const digest = await sha256Hex(new TextEncoder().encode(JSON.stringify({ scopeId, label: canonicalLabel })));
+    return Object.freeze({ id: `entity.${digest}`, label: canonicalLabel });
+}
+async function normalizeProviderExtraction(value, request, diagnostics) {
+    const result = record(value, "world_fact_provider_result_invalid");
+    // 仅保留给显式注入的本地/test harness；真实 provider schema 不包含此分支。
+    if (result.schema === WORLD_FACT_EXTRACTION_RESULT_SCHEMA && Array.isArray(result.facts))
+        return result;
+    exactKeys(result, ["facts"], "world_fact_provider_result_shape_invalid");
+    if (!Array.isArray(result.facts))
+        throw new Error("world_fact_provider_result_invalid");
+    return {
+        schema: WORLD_FACT_EXTRACTION_RESULT_SCHEMA,
+        facts: (await Promise.all(result.facts.map(async (candidate, index) => {
+            try {
+                const fact = record(candidate, `world_fact_provider_${index}_invalid`);
+                const keys = Object.keys(fact);
+                if (!(keys.length === PROVIDER_FACT_KEYS.length || keys.length === PROVIDER_FACT_KEYS.length + 1)
+                    || !PROVIDER_FACT_KEYS.every((key) => Object.hasOwn(fact, key))
+                    || (keys.length > PROVIDER_FACT_KEYS.length && !Object.hasOwn(fact, "qualifiers_json"))) {
+                    throw new Error(`world_fact_provider_${index}_shape_invalid`);
+                }
+                const decodedValue = parseJson(fact.object_value_json, `world_fact_provider_${index}_object_json_invalid`);
+                let object;
+                if (fact.object_type === "string" && typeof decodedValue === "string")
+                    object = { type: "string", value: decodedValue };
+                else if (fact.object_type === "number" && typeof decodedValue === "number")
+                    object = { type: "number", value: decodedValue };
+                else if (fact.object_type === "boolean" && typeof decodedValue === "boolean")
+                    object = { type: "boolean", value: decodedValue };
+                else if (fact.object_type === "entity") {
+                    const entityLabel = typeof decodedValue === "string" ? decodedValue : record(decodedValue, `world_fact_provider_${index}_entity_invalid`).label;
+                    object = { type: "entity", value: await stableEntityId(request.source.scopeId, entityLabel, `world_fact_provider_${index}_entity_invalid`) };
+                }
+                else if (fact.object_type === "json")
+                    object = { type: "json", value: decodedValue };
+                else
+                    throw new Error(`world_fact_provider_${index}_object_type_invalid`);
+                const qualifiers = fact.qualifiers_json === undefined ? {} : parseJson(fact.qualifiers_json, `world_fact_provider_${index}_qualifiers_invalid`);
+                return [{
+                        kind: fact.object_type === "entity" ? "relation" : "attribute",
+                        subject: await stableEntityId(request.source.scopeId, fact.subject_label, `world_fact_provider_${index}_subject_label_invalid`),
+                        predicate: normalizedProviderText(fact.predicate, `world_fact_provider_${index}_predicate_invalid`),
+                        object,
+                        qualifiers,
+                        confidence: fact.confidence,
+                        evidence: normalizeEvidence(fact, request.chunk.text, index),
+                    }];
+            }
+            catch (error) {
+                rejectFact(diagnostics, error, "world_fact_provider_normalization_invalid");
+                return [];
+            }
+        }))).flat(),
+    };
+}
+async function validatedProviderExtraction(value, request, diagnostics) {
+    const normalized = record(await normalizeProviderExtraction(value, request, diagnostics), "world_fact_provider_normalized_invalid");
+    if (!Array.isArray(normalized.facts))
+        throw new Error("world_fact_provider_normalized_invalid");
+    const facts = normalized.facts.flatMap((fact) => {
+        try {
+            return [...decodeWorldFactExtractionResult({ schema: WORLD_FACT_EXTRACTION_RESULT_SCHEMA, facts: [fact] }, request.chunk)];
+        }
+        catch (error) {
+            rejectFact(diagnostics, error, "world_fact_schema_invalid");
+            return [];
+        }
+    });
+    return { schema: WORLD_FACT_EXTRACTION_RESULT_SCHEMA, facts };
+}
+function entitiesFrom(value) {
+    const result = record(value, "authoring_ingestion_world_get_invalid");
+    if (!Array.isArray(result.entities))
+        throw new Error("authoring_ingestion_world_get_invalid");
+    return result.entities.map((entity) => record(entity, "authoring_ingestion_world_entity_invalid"));
+}
+function reconciliationSnapshotFrom(value) {
+    const result = record(value, "authoring_ingestion_world_get_invalid");
+    if (!Array.isArray(result.entities) || !Array.isArray(result.relations))
+        throw new Error("authoring_ingestion_world_get_invalid");
+    return Object.freeze({
+        entities: Object.freeze(result.entities.map((value) => {
+            const entity = record(value, "authoring_ingestion_world_entity_invalid");
+            if (typeof entity.id !== "string" || typeof entity.kind !== "string")
+                throw new Error("authoring_ingestion_world_entity_invalid");
+            return Object.freeze({ id: entity.id, kind: entity.kind, props: record(entity.props, "authoring_ingestion_world_entity_invalid") });
+        })),
+        relations: Object.freeze(result.relations.map((value) => {
+            const relation = record(value, "authoring_ingestion_world_relation_invalid");
+            if (typeof relation.src !== "string" || typeof relation.dst !== "string" || typeof relation.kind !== "string")
+                throw new Error("authoring_ingestion_world_relation_invalid");
+            return Object.freeze({ src: relation.src, dst: relation.dst, kind: relation.kind, props: record(relation.props, "authoring_ingestion_world_relation_invalid") });
+        })),
+    });
+}
+function receiptFrom(value) {
+    const receipt = record(value, "authoring_ingestion_receipt_invalid");
+    if (receipt.schema_version !== 1 || typeof receipt.operation_id !== "string"
+        || !Number.isSafeInteger(receipt.previous_project_revision)
+        || !Number.isSafeInteger(receipt.next_project_revision)
+        || receipt.readback_verified !== true) {
+        throw new Error("authoring_ingestion_receipt_invalid");
+    }
+    return receipt;
+}
+function factsFromBatch(batch) {
+    const facts = new Map();
+    for (const entity of batch.entities) {
+        const values = entity.props.facts;
+        if (!Array.isArray(values))
+            continue;
+        for (const value of values) {
+            const fact = record(value, "authoring_ingestion_fact_invalid");
+            if (typeof fact.factId !== "string" || typeof fact.scopeId !== "string")
+                throw new Error("authoring_ingestion_fact_invalid");
+            facts.set(`${fact.scopeId}\0${fact.factId}`, fact);
+        }
+    }
+    return Object.freeze([...facts.values()].sort((left, right) => left.factId.localeCompare(right.factId)));
+}
+function createExtractor(connection, diagnostics) {
+    return Object.freeze({
+        harness: connection.structuredJson.providerId,
+        model: connection.structuredJson.modelId,
+        contractVersion: WORLD_FACT_EXTRACTION_RESULT_SCHEMA,
+        async extract(request) {
+            const runAttempt = async (retry) => {
+                const attemptDiagnostics = { rejectedFactCount: 0, correctedEvidenceCount: 0, committedFacts: [], rejectionReasons: {}, unverifiedChunkIndexes: [] };
+                const result = await connection.structuredJson.generate({
+                    schemaName: "world_fact_extraction",
+                    jsonSchema: EXTRACTION_JSON_SCHEMA,
+                    messages: [
+                        {
+                            role: "system",
+                            content: "你是世界设定事实抽取器。只输出符合 schema 的 JSON，提取 chunk 中所有明确、原子、对自然语言问答有用的事实，不猜测也不因数量省略。subject_label 使用原文检索主体；predicate 必须是简短具体的 snake_case，并保持方向，例如地点的 current_responsible_person 指向责任人。object_value_json 必须是 JSON 值序列化后的字符串：string 写 JSON 字符串，number/boolean 写对应 JSON，entity 写 {\"label\":\"原文名称\"}，复合答案才用 json。evidence_quote 必须完整逐字复制能独立证明事实的最短原文句子或分句；遇到“这里”“其”“该物件”等代词时，quote 必须连同前句中明确先行词一起复制。不得改写、省略、拼接或添加字符。不要生成 ID、offset 或 schema 外字段。" + (retry ? " 上次有事实无法由原文证明；本次务必重新选择包含明确主体、关系和答案且在 chunk 中唯一的连续完整原句。" : ""),
+                        },
+                        {
+                            role: "user",
+                            content: JSON.stringify({
+                                schema: request.schema,
+                                source: request.source,
+                                chunk: request.chunk,
+                                outputSchema: request.outputSchema,
+                            }),
+                        },
+                    ],
+                });
+                const value = await validatedProviderExtraction(result.value, request, attemptDiagnostics);
+                const factCount = record(value, "world_fact_provider_normalized_invalid").facts.length;
+                return { value, factCount, diagnostics: attemptDiagnostics };
+            };
+            const first = await runAttempt(false);
+            let attempts = [first];
+            if (first.factCount === 0 || first.diagnostics.rejectedFactCount > first.factCount) {
+                try {
+                    attempts = [first, await runAttempt(true)];
+                }
+                catch {
+                    first.diagnostics.rejectedFactCount += 1;
+                    first.diagnostics.rejectionReasons.world_fact_retry_failed = (first.diagnostics.rejectionReasons.world_fact_retry_failed ?? 0) + 1;
+                }
+            }
+            const mergedFacts = new Map();
+            for (const attempt of attempts) {
+                const facts = record(attempt.value, "world_fact_provider_normalized_invalid").facts;
+                if (!Array.isArray(facts))
+                    throw new Error("world_fact_provider_normalized_invalid");
+                for (const fact of facts)
+                    mergedFacts.set(JSON.stringify(fact), fact);
+                diagnostics.rejectedFactCount += attempt.diagnostics.rejectedFactCount;
+                diagnostics.correctedEvidenceCount += attempt.diagnostics.correctedEvidenceCount;
+            }
+            for (const [code, count] of attempts.flatMap((attempt) => Object.entries(attempt.diagnostics.rejectionReasons))) {
+                diagnostics.rejectionReasons[code] = (diagnostics.rejectionReasons[code] ?? 0) + count;
+            }
+            if (mergedFacts.size === 0)
+                diagnostics.unverifiedChunkIndexes.push(request.chunk.index);
+            return { schema: WORLD_FACT_EXTRACTION_RESULT_SCHEMA, facts: [...mergedFacts.values()] };
+        },
+    });
+}
+function createAuthority(host, connection, diagnostics, source, observedMarker, expectedProjectRevision) {
+    return Object.freeze({
+        async commit(batch) {
+            const facts = factsFromBatch(batch);
+            if (facts.length === 0)
+                throw new Error("authoring_ingestion_no_valid_facts");
+            diagnostics.committedFacts = facts.map((fact) => ({ scopeId: fact.scopeId, factId: fact.factId }));
+            const ids = ingestionSourceReconciliationReadIds({
+                scopeId: source.scopeId,
+                sourceId: source.sourceId,
+                batch,
+                marker: observedMarker,
+            });
+            const snapshot = reconciliationSnapshotFrom(await host.dispatchTool({ name: "world_get", input: { ids, include_relations: true } }));
+            const reconciliation = reconcileIngestionSource({
+                scopeId: source.scopeId,
+                sourceId: source.sourceId,
+                sourceRevision: source.sourceRevision,
+                batch,
+                expectedCurrentBatchId: observedMarker?.currentBatchId ?? null,
+                snapshot,
+            });
+            if (reconciliation.status === "already_committed") {
+                return { status: "already_committed", version: String(expectedProjectRevision) };
+            }
+            const searchableUpserts = reconciliation.operations.filter((operation) => operation.type === "upsert_entity" && operation.kind !== INGESTION_SOURCE_CONTROL_KIND);
+            const embeddings = searchableUpserts.length === 0 ? [] : await connection.embedding.embed(searchableUpserts.map((operation) => {
+                const text = operation.props.index_text;
+                if (typeof text !== "string")
+                    throw new Error("authoring_ingestion_index_text_missing");
+                return text;
+            }));
+            if (embeddings.length !== searchableUpserts.length)
+                throw new Error("authoring_ingestion_embedding_count_invalid");
+            const embeddingById = new Map(searchableUpserts.map((operation, index) => [operation.id, embeddings[index]]));
+            const operations = reconciliation.operations.map((operation) => operation.type === "upsert_entity" && operation.kind !== INGESTION_SOURCE_CONTROL_KIND
+                ? { ...operation, props: { ...operation.props, embedding: embeddingById.get(operation.id) } }
+                : { ...operation });
+            const receipt = receiptFrom(await host.dispatchTool({
+                name: "world_apply",
+                input: { operations },
+                effect_identity: {
+                    operation_id: `world_ingest_${batch.batchId}`,
+                    expected_project_revision: expectedProjectRevision,
+                },
+            }));
+            const markerId = ingestionSourceMarkerId(source.scopeId, source.sourceId);
+            const readback = entitiesFrom(await host.dispatchTool({ name: "world_get", input: { ids: [markerId] } }));
+            if (!readback.some((entity) => entity.id === markerId))
+                throw new Error("authoring_ingestion_readback_failed");
+            return { status: "committed", version: String(receipt.next_project_revision) };
+        },
+        async read(input) {
+            const id = ingestionFactEntityId(input.scopeId, input.factId);
+            const entities = entitiesFrom(await host.dispatchTool({ name: "world_get", input: { ids: [id] } }));
+            const entity = entities.find((candidate) => candidate.id === id);
+            if (entity === undefined)
+                return null;
+            const fact = record(entity.props, "authoring_ingestion_fact_props_invalid").fact;
+            if (fact?.scopeId !== input.scopeId || fact.factId !== input.factId)
+                throw new Error("authoring_ingestion_fact_readback_invalid");
+            return fact;
+        },
+        async resolve(input) {
+            const result = record(await host.dispatchTool({
+                name: "world_search",
+                input: {
+                    query: input.query,
+                    mode: "semantic",
+                    limit: Math.min(100, Math.max(input.limit * 4, input.limit)),
+                    filters: { scope_id: input.scopeId },
+                },
+            }), "authoring_ingestion_world_search_invalid");
+            if (!Array.isArray(result.results))
+                throw new Error("authoring_ingestion_world_search_invalid");
+            const candidates = result.results.map((value) => record(value, "authoring_ingestion_world_hit_invalid"));
+            const maximumScore = Math.max(0, ...candidates.map((hit) => typeof hit.score === "number" && Number.isFinite(hit.score) ? hit.score : 0));
+            const hits = [];
+            const seen = new Set();
+            for (const hit of candidates) {
+                const props = record(hit.props, "authoring_ingestion_world_hit_props_invalid");
+                const fact = props.fact;
+                if (fact?.scopeId !== input.scopeId || typeof fact.factId !== "string" || seen.has(fact.factId))
+                    continue;
+                const rawScore = typeof hit.score === "number" && Number.isFinite(hit.score) ? hit.score : 0;
+                const relevance = maximumScore === 0 ? 0 : Math.min(1, rawScore / maximumScore);
+                if (relevance < input.minimumRelevance)
+                    continue;
+                const channels = Array.isArray(hit.channels) && hit.channels.includes("semantic") ? ["semantic"] : [];
+                if (channels.length === 0)
+                    continue;
+                seen.add(fact.factId);
+                hits.push({ fact, relevance, channels });
+            }
+            return Object.freeze(hits.slice(0, input.limit));
+        },
+    });
+}
+/**
+ * 把全文抽取、真实 embedding 与 Host authority commit 串成一个作者调用。
+ * 唯一持久化入口是 host.dispatchTool(world_apply)，不得直接写 Ladybug checkpoint。
+ */
+export async function ingestProjectDocument(host, source, capability) {
+    capability.modelConnection.assertAvailable?.(["structured", "embedding"]);
+    const diagnostics = { rejectedFactCount: 0, correctedEvidenceCount: 0, committedFacts: [], rejectionReasons: {}, unverifiedChunkIndexes: [] };
+    // revision 与 source marker 属于同一个 reconcile preimage，必须在任何模型/embedding 调用前冻结。
+    const observedStatus = await host.inspect();
+    const sourceMarkerId = ingestionSourceMarkerId(source.scopeId, source.sourceId);
+    const initialSnapshot = reconciliationSnapshotFrom(await host.dispatchTool({
+        name: "world_get",
+        input: { ids: [sourceMarkerId], include_relations: false },
+    }));
+    const observedMarker = readIngestionSourceMarker(initialSnapshot, source.scopeId, source.sourceId);
+    const operations = createNaturalLanguageWorldOperations({
+        authority: createAuthority(host, capability.modelConnection, diagnostics, source, observedMarker, observedStatus.project_revision),
+        extractor: createExtractor(capability.modelConnection, diagnostics),
+        ...(capability.maximumConcurrentExtractions === undefined ? {} : { maximumConcurrentExtractions: capability.maximumConcurrentExtractions }),
+        chunking: capability.chunking ?? { maximumCharacters: 450, overlapCharacters: 80 },
+        ...(capability.clock === undefined ? {} : { clock: capability.clock }),
+    });
+    const receipt = await operations.commit(source);
+    const warnings = [];
+    if (diagnostics.rejectedFactCount > 0)
+        warnings.push({ code: "world_facts_rejected", count: diagnostics.rejectedFactCount });
+    if (diagnostics.correctedEvidenceCount > 0)
+        warnings.push({ code: "evidence_offsets_corrected", count: diagnostics.correctedEvidenceCount });
+    const unverifiedChunkIndexes = Object.freeze([...new Set(diagnostics.unverifiedChunkIndexes)].sort((left, right) => left - right));
+    if (unverifiedChunkIndexes.length > 0)
+        warnings.push({ code: "unverified_chunks", count: unverifiedChunkIndexes.length });
+    return Object.freeze({
+        ...receipt,
+        completeness: diagnostics.rejectedFactCount === 0 && unverifiedChunkIndexes.length === 0 ? "complete" : "partial",
+        rejectedFactCount: diagnostics.rejectedFactCount,
+        correctedEvidenceCount: diagnostics.correctedEvidenceCount,
+        warnings: Object.freeze(warnings),
+        committedFacts: Object.freeze(diagnostics.committedFacts.map((fact) => Object.freeze(fact))),
+        rejectionReasons: Object.freeze(Object.fromEntries(Object.entries(diagnostics.rejectionReasons).sort(([left], [right]) => left.localeCompare(right)))),
+        unverifiedChunkCount: unverifiedChunkIndexes.length,
+        unverifiedChunkIndexes,
+    });
+}

package/dist/authoring-model-connection.d.ts

@@ -0,0 +1,166 @@
+/**
+ * 作者侧真实模型连接。认证材料仅存在于 host process 内存和请求 header 中，
+ * 错误对象、usage 与返回值都不会携带 token、底层响应正文或请求 URL。
+ */
+export declare const AUTHORING_EMBEDDING_MODEL_ALLOWLIST: readonly ["qwen/qwen3-embedding-8b", "qwen/qwen3-embedding-4b", "openai/text-embedding-3-small"];
+export declare const EMBEDDING_BATCH_SIZE = 128;
+declare const OPENROUTER_PRODUCTION_BASE_URL = "https://openrouter.ai/api/v1";
+declare const DEEPSEEK_PRODUCTION_BASE_URL = "https://api.deepseek.com";
+declare const DEEPSEEK_V4_FLASH_MODEL = "deepseek-v4-flash";
+export type AuthoringModelConnectionErrorCode = "invalid_configuration" | "embedding_credentials_missing" | "structured_credentials_missing" | "invalid_request" | "aborted" | "timeout" | "transport_failed" | "provider_rejected" | "provider_model_mismatch" | "provider_output_truncated" | "provider_response_invalid";
+export type AuthoringModelFinishReason = "stop" | "length" | "tool_calls" | "content_filter" | "error" | "other" | "missing";
+export type AuthoringModelContentType = "string" | "array" | "object" | "number" | "boolean" | "null" | "undefined";
+export type AuthoringJsonFraming = "bare_json" | "single_json_fence";
+export interface AuthoringJsonParseIssue {
+    readonly layer: "http_envelope" | "model_output";
+    readonly position: number | null;
+}
+/** 只含固定枚举和长度，不携带 provider 正文、URL、model 或认证材料。 */
+export interface AuthoringModelResponseMetadata {
+    readonly finishReason: AuthoringModelFinishReason;
+    readonly contentType: AuthoringModelContentType;
+    readonly contentLength: number | null;
+    readonly framing?: AuthoringJsonFraming;
+}
+export type AuthoringJsonSchemaIssueKeyword = "type" | "required" | "additionalProperties" | "enum" | "pattern" | "minLength" | "maxLength" | "minimum" | "maximum" | "minItems" | "maxItems";
+/** 只含 schema 路径与固定 keyword，不包含 candidate value。 */
+export interface AuthoringJsonSchemaIssue {
+    readonly path: string;
+    readonly keyword: AuthoringJsonSchemaIssueKeyword;
+}
+export type AuthoringModelValidationStage = "closed_schema" | "usage" | "response_parse" | "response_shape";
+/** 所有失败都是可穷举、已脱敏的 terminal result；本模块绝不静默降级。 */
+export declare class AuthoringModelConnectionError extends Error {
+    readonly code: AuthoringModelConnectionErrorCode;
+    readonly retryable: boolean;
+    readonly status?: number | undefined;
+    readonly responseMetadata?: AuthoringModelResponseMetadata | undefined;
+    readonly schemaIssue?: AuthoringJsonSchemaIssue | undefined;
+    readonly validationStage?: AuthoringModelValidationStage | undefined;
+    readonly parseIssue?: AuthoringJsonParseIssue | undefined;
+    readonly name: string;
+    readonly terminal: true;
+    readonly validationIssues: readonly AuthoringJsonSchemaIssue[];
+    constructor(code: AuthoringModelConnectionErrorCode, retryable: boolean, status?: number | undefined, responseMetadata?: AuthoringModelResponseMetadata | undefined, schemaIssue?: AuthoringJsonSchemaIssue | undefined, validationStage?: AuthoringModelValidationStage | undefined, parseIssue?: AuthoringJsonParseIssue | undefined);
+}
+export interface AuthoringModelUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly requests: number;
+    /** 实际发起的 HTTP 次数；tokens/requests 只累计收到且验证通过的 provider usage，丢失响应的计费未知。 */
+    readonly requestAttempts?: number;
+    readonly providerId?: string;
+    readonly modelId?: string;
+    readonly cachedInputTokens?: number;
+    readonly byProviderModel?: readonly AuthoringProviderModelUsage[];
+}
+export interface AuthoringProviderModelUsage {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly cachedInputTokens?: number;
+    readonly requests: number;
+    readonly requestAttempts?: number;
+}
+export interface AuthoringEmbeddingPort {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly dimensions: number;
+    /** embedding provider 的 canonical URL origin；cache identity 不得从 providerId 猜测。 */
+    readonly origin?: string;
+    /** provider/policy descriptor identity；存在时必须进入 cache identity。 */
+    readonly descriptorSha256?: string;
+    readonly descriptorSha256ByInputKind?: Readonly<{
+        document: string;
+        query: string;
+    }>;
+    embed(texts: readonly string[], options?: Readonly<{
+        signal?: AbortSignal;
+        inputKind?: "document" | "query";
+    }>): Promise<readonly (readonly number[])[]>;
+}
+export type AuthoringStructuredMessage = Readonly<{
+    role: "system" | "user" | "assistant";
+    content: string;
+}>;
+export type AuthoringStructuredTaskMode = "extraction" | "simulation_retrieval" | "full_book_planning";
+export type AuthoringStructuredJsonRequest = Readonly<{
+    schemaName: string;
+    jsonSchema: Readonly<Record<string, unknown>>;
+    messages: readonly AuthoringStructuredMessage[];
+    taskMode?: AuthoringStructuredTaskMode;
+    /** 仅 production D4F 支持；未指定时保持 none，显式禁用配置不能被 low 覆盖。 */
+    reasoningEffort?: "none" | "low";
+    maxOutputTokens?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}>;
+export type AuthoringStructuredJsonResult<T = unknown> = Readonly<{
+    value: T;
+    usage: AuthoringModelUsage;
+    /** 只允许单一完整 json 围栏的传输解包；解包后仍须通过完整 schema。 */
+    framing?: AuthoringJsonFraming;
+}>;
+export interface AuthoringStructuredJsonPort {
+    readonly providerId: string;
+    readonly modelId: string;
+    generate<T = unknown>(request: AuthoringStructuredJsonRequest): Promise<AuthoringStructuredJsonResult<T>>;
+}
+export interface AuthoringModelConnection {
+    readonly embedding: AuthoringEmbeddingPort;
+    readonly structuredJson: AuthoringStructuredJsonPort;
+    /** 在任何可能计费的调用前验证本阶段实际需要的 provider port。 */
+    assertAvailable?(ports: readonly ("embedding" | "structured")[]): void;
+    usage(): AuthoringModelUsage;
+}
+export type AuthoringRetryConfig = Readonly<{
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}>;
+export type OpenAiCompatibleAuthoringModelConfig = Readonly<{
+    /** 只能由 host process 环境或私有 capability 注入。 */
+    apiKey: string;
+    embeddingModel: (typeof AUTHORING_EMBEDDING_MODEL_ALLOWLIST)[number];
+    embeddingDimensions: number;
+    structuredChatModel: string;
+    /** structuredChatModel 必须显式位于此名单，禁止调用方任意透传 model。 */
+    structuredChatModelAllowlist: readonly string[];
+    baseUrl?: string;
+    /** 自定义 OpenAI-compatible origin/path 也必须由 host 显式放行。 */
+    baseUrlAllowlist?: readonly string[];
+    timeoutMs?: number;
+    retry?: AuthoringRetryConfig;
+}>;
+export type ProductionAuthoringModelConfig = Readonly<{
+    embedding: Readonly<{
+        apiKey: string;
+        baseUrl?: typeof OPENROUTER_PRODUCTION_BASE_URL;
+        model?: "qwen/qwen3-embedding-8b";
+        dimensions?: 1024;
+        timeoutMs?: number;
+    }>;
+    structured: Readonly<{
+        apiKey: string;
+        baseUrl?: typeof DEEPSEEK_PRODUCTION_BASE_URL;
+        model?: typeof DEEPSEEK_V4_FLASH_MODEL;
+        thinking?: "disabled";
+        responseFormat?: "json_schema";
+        defaultTaskMode?: AuthoringStructuredTaskMode;
+        /** 结构化任务的试用采样参数；默认值不是统计稳定性保证。 */
+        temperature?: number;
+        maxOutputTokens?: number;
+        timeoutMs?: number;
+    }>;
+    retry?: AuthoringRetryConfig;
+}>;
+export declare function createOpenAiCompatibleAuthoringModelConnection(config: OpenAiCompatibleAuthoringModelConfig): AuthoringModelConnection;
+/**
+ * 生产作者模型连接：embedding 固定走 OpenRouter/Qwen3，structured JSON 固定走
+ * DeepSeek 官方 Responses API/V4 Flash；两个 credential 永远位于不同 poster closure。
+ */
+export declare function createProductionAuthoringModelConnection(config: ProductionAuthoringModelConfig): AuthoringModelConnection;
+export {};