@world-engines/scenario-review-snapshot 0.0.0

package/dist/neutral-artifact-assembler.d.ts

@@ -0,0 +1,180 @@
+import { type NeutralSourceCompileInput } from "@world-engines/scenario-author-source";
+import { type CompileNeutralScenarioSourceOutcome, type CompileTargetProfile, type MusicCandidateSourceV3, type NeutralCompiledSpatialBase, type NeutralSourceCompilerReceipt, type TriggerDocumentV3, type ViewInteractionManifestV3, type ViewInteractionSourceV3 } from "@world-engines/tmw";
+import { type FrozenPublishInput, type FrozenPublishResource, type FrozenRuntimeIdentity, type FrozenSystemPrompt } from "./artifact.js";
+import type { JsonValue } from "./types.js";
+export declare const NEUTRAL_ARTIFACT_EMBEDDING_INDEX_PATH: "__derived__/embedding-index-v1.json";
+export declare const FRESH_RUNTIME3_PLAYER_TURN_POLICY_SCHEMA_VERSION: 1;
+export interface FrozenArtifactEmbeddingSourceIdentity {
+    readonly owner_id: string;
+    readonly scenario_id: string;
+    readonly source_revision: number;
+    readonly revision_digest: string;
+}
+export interface FrozenArtifactEmbeddingRequestEntity {
+    readonly entity_id: string;
+    readonly source_kind: "entity" | "chunk" | "statement" | "edge_assertion";
+    readonly source_text: string;
+    readonly source_text_sha256: string;
+}
+export interface FrozenArtifactEmbeddingBatchRequest {
+    readonly source: FrozenArtifactEmbeddingSourceIdentity;
+    readonly entities: readonly FrozenArtifactEmbeddingRequestEntity[];
+    readonly signal?: AbortSignal;
+}
+export interface FrozenArtifactEmbeddingDescriptor {
+    readonly provider: string;
+    readonly model: string;
+    readonly dimension: number;
+    readonly descriptor_sha256: string;
+    readonly source_revision: number;
+    readonly source_revision_digest: string;
+}
+export interface FrozenArtifactEmbeddingEntry {
+    readonly entity_id: string;
+    readonly source_kind: FrozenArtifactEmbeddingRequestEntity["source_kind"];
+    readonly source_text_sha256: string;
+    readonly vector: readonly number[];
+}
+export interface FrozenArtifactEmbeddingBatchResult {
+    readonly descriptor: FrozenArtifactEmbeddingDescriptor;
+    readonly entries: readonly FrozenArtifactEmbeddingEntry[];
+}
+export type FrozenArtifactEmbeddingBatch = (request: FrozenArtifactEmbeddingBatchRequest) => Promise<FrozenArtifactEmbeddingBatchResult>;
+export interface NeutralArtifactGraphProjection {
+    readonly entities: readonly JsonValue[];
+    readonly relations: readonly JsonValue[];
+}
+export interface NeutralArtifactEmbeddingMaterialization {
+    readonly descriptor: FrozenArtifactEmbeddingDescriptor;
+    readonly vector_by_entity_id: ReadonlyMap<string, readonly number[]>;
+    readonly index_resource: FrozenPublishResource;
+}
+/** `scenario-database-codec Rust crate` WASM 的唯一调用 seam；Browser 与 Node 注入同一 adapter。 */
+export interface FrozenDatabaseCodecV1Input {
+    readonly graph_v5_json: Uint8Array;
+    readonly embedding_index_v1_json: Uint8Array;
+    readonly vector_values: Float64Array;
+    readonly sidecar_v5_json: Uint8Array;
+}
+export interface FrozenDatabaseCodecV1Result {
+    readonly codec: "frozen-database-v1";
+    readonly vector_dtype: "f32-le" | "f64-le";
+    readonly bytes: Uint8Array;
+}
+export type PackFrozenDatabase = (input: FrozenDatabaseCodecV1Input) => Promise<FrozenDatabaseCodecV1Result>;
+export declare const FROZEN_DATABASE_VIEW_ACCESS_POLICY_SCHEMA_VERSION: 3;
+/**
+ * 新 frozen database 只传 graph-v5 的 policy identity。Player/Edge 必须从同一
+ * graph 完整还原 V2 subjects 并校验 digest；旧 V2 full-subject wire 仅供 reader 兼容。
+ */
+export interface FrozenDatabaseDerivedViewAccessPolicyV3 {
+    readonly schemaVersion: typeof FROZEN_DATABASE_VIEW_ACCESS_POLICY_SCHEMA_VERSION;
+    readonly derivation: "graph-v5";
+    readonly policySha256: readonly number[];
+}
+/** 已通过同一深模块完整校验，可供 Host 只读 query adapter 消费；读取不会触发 provider。 */
+export interface PreparedNeutralArtifactEmbeddingSnapshot {
+    readonly source: FrozenArtifactEmbeddingSourceIdentity;
+    readonly batch: FrozenArtifactEmbeddingBatchResult;
+    readonly materialization: NeutralArtifactEmbeddingMaterialization;
+}
+export interface NeutralArtifactCompiler<TProfile, TResult> {
+    compile(input: NeutralSourceCompileInput, profile: TProfile): Promise<TResult>;
+}
+export interface CapturedNeutralArtifactCompilation<TResult> {
+    readonly source: NeutralSourceCompileInput;
+    readonly compilation: TResult;
+}
+export declare const NEUTRAL_ARTIFACT_DERIVED_RESOURCE_PREFIX: "__derived__/";
+export interface NeutralArtifactRuntimeDefinitions {
+    readonly triggers: readonly JsonValue[];
+    readonly trigger_variables_schema: readonly JsonValue[];
+    readonly cg_defs: readonly JsonValue[];
+    readonly achievement_defs: readonly JsonValue[];
+    readonly transaction_defs: readonly JsonValue[];
+}
+export interface NeutralArtifactSourceModel<TViewProject = unknown> {
+    readonly metadata: JsonValue;
+    readonly protagonist: JsonValue;
+    readonly system_prompts: readonly FrozenSystemPrompt[];
+    readonly graph: NeutralArtifactGraphProjection;
+    readonly trigger_document: TriggerDocumentV3;
+    readonly compiled_plan: JsonValue;
+    readonly view_project: TViewProject;
+    readonly view_source_bytes: Uint8Array;
+    readonly view_interaction_mobile: ViewInteractionSourceV3 | null;
+    readonly view_interaction_pc: ViewInteractionSourceV3 | null;
+    readonly music_candidate_source: MusicCandidateSourceV3;
+    readonly retrieval: JsonValue;
+    readonly runtime_definitions: NeutralArtifactRuntimeDefinitions;
+    readonly source_metadata: Readonly<Record<string, JsonValue>>;
+    readonly resources: readonly FrozenPublishResource[];
+    readonly spatial_world: NeutralCompiledSpatialBase | null;
+}
+export interface NeutralArtifactCompilation<TViewProject = unknown> {
+    readonly profile: CompileTargetProfile;
+    readonly profile_digest: string;
+    readonly receipt: NeutralSourceCompilerReceipt;
+    readonly model: NeutralArtifactSourceModel<TViewProject>;
+    readonly witness_resources: readonly FrozenPublishResource[];
+}
+export interface NeutralArtifactCompilerWitnessInput {
+    readonly source: NeutralSourceCompileInput;
+    readonly target_profile_bytes: Uint8Array;
+    readonly target_profile_digest: string;
+    readonly compiler_receipt_bytes: Uint8Array;
+    readonly compiler_receipt_digest: string;
+}
+export type NeutralArtifactViewProjectAdapter<TViewProject> = (canonicalGzipTar: Uint8Array) => Promise<TViewProject>;
+export interface AssembleNeutralFrozenPublishInput<TViewProject = unknown> {
+    readonly source: NeutralSourceCompileInput;
+    readonly content_epoch: number;
+    readonly compilation: NeutralArtifactCompilation<TViewProject>;
+    readonly embedding: NeutralArtifactEmbeddingMaterialization;
+    readonly database_bytes: Uint8Array;
+    readonly database_delivery_bytes: Uint8Array;
+    readonly view_publish_mobile_bytes: Uint8Array;
+    readonly view_publish_pc_bytes: Uint8Array;
+    readonly runtime_identity: FrozenRuntimeIdentity;
+}
+export interface EncodeNeutralReviewDatabaseInput<TViewProject = unknown> {
+    readonly source: NeutralSourceCompileInput;
+    readonly content_epoch: number;
+    readonly compilation: NeutralArtifactCompilation<TViewProject>;
+    readonly embedding: NeutralArtifactEmbeddingMaterialization;
+    readonly packFrozenDatabase: PackFrozenDatabase;
+}
+/** ADR-0148 canonical source text: enabled incident relations enrich both endpoint entities. */
+export declare function deriveNeutralArtifactEntityEmbeddingSourceText(entityValue: JsonValue, graph: NeutralArtifactGraphProjection): string;
+export declare function compileCapturedNeutralSource<TProfile, TResult>(source: NeutralSourceCompileInput, profile: TProfile, compiler: NeutralArtifactCompiler<TProfile, TResult>): Promise<CapturedNeutralArtifactCompilation<TResult>>;
+/**
+ * Runtime3 的 player turn 只消费已编译计划中的 policy 段；不回读 ArtifactV5 中
+ * 已退役的 metadata/system_prompts identity pair。policy digest 只覆盖可执行作者语义
+ * 与 runtime contract，Artifact/head/five-object identity 由 Edge verified reader 再绑定。
+ */
+export declare function attachFreshRuntime3PlayerTurnPolicy(compiledPlan: JsonValue, prompts: readonly FrozenSystemPrompt[], runtimeContractHash: string): JsonValue;
+/**
+ * 把一次成功 compiler outcome 物化为 Browser/Node 共用的发布模型。
+ * gzip-tar 解包是唯一外部 seam；调用方不能重写 compiler derived-object 解释规则。
+ */
+export declare function materializeNeutralArtifactCompilation<TViewProject>(source: NeutralSourceCompileInput, profile: CompileTargetProfile, outcome: Extract<CompileNeutralScenarioSourceOutcome, {
+    readonly ok: true;
+}>, unpackViewProject: NeutralArtifactViewProjectAdapter<TViewProject>): Promise<NeutralArtifactCompilation<TViewProject>>;
+export declare function buildNeutralArtifactWitnessResources(input: NeutralArtifactCompilerWitnessInput): Promise<readonly FrozenPublishResource[]>;
+export declare function mergeNeutralArtifactResources(authorResources: readonly FrozenPublishResource[], witnessResources: readonly FrozenPublishResource[], derivedResources?: readonly FrozenPublishResource[]): readonly FrozenPublishResource[];
+/**
+ * 编译产物取得最终 epoch/artifact identity 时，保留 source 中的完整下行声明。
+ * source digest 先验证，避免 compiler 以未签名声明扩展 View SDK 面。
+ */
+export declare function bindViewInteractionManifestForFrozenArtifact(source: ViewInteractionSourceV3 | null, epoch: number, runtimeContractHash: string, artifactBytes: Uint8Array): Promise<ViewInteractionManifestV3 | null>;
+/**
+ * 由 compiler materialization 直接生成 fresh-only compact database v1；Browser
+ * 与 Node 必须注入同一 Rust/WASM adapter，禁止在 JS 内先拼出含向量的完整 JSON。
+ */
+export declare function encodeNeutralReviewDatabaseSnapshot<TViewProject>(input: EncodeNeutralReviewDatabaseInput<TViewProject>): Promise<Uint8Array>;
+/** 最终 FrozenPublishInput 唯一共享装配点；返回前执行 ArtifactV5 全量 normalization。 */
+export declare function assembleNeutralFrozenPublishInput<TViewProject>(input: AssembleNeutralFrozenPublishInput<TViewProject>): Promise<FrozenPublishInput>;
+/** Formal freeze 与本地 authoring recall 共用的唯一 corpus 文本投影；关系索引每批只构建一次。 */
+export declare function projectNeutralArtifactEmbeddingSources(graph: NeutralArtifactGraphProjection): readonly Readonly<Pick<FrozenArtifactEmbeddingRequestEntity, "entity_id" | "source_kind" | "source_text">>[];
+export declare function prepareNeutralArtifactEmbeddingSnapshot(graph: NeutralArtifactGraphProjection, source: FrozenArtifactEmbeddingSourceIdentity, runBatch: FrozenArtifactEmbeddingBatch, signal?: AbortSignal): Promise<PreparedNeutralArtifactEmbeddingSnapshot>;
+export declare function materializeNeutralArtifactEmbeddings(graph: NeutralArtifactGraphProjection, source: FrozenArtifactEmbeddingSourceIdentity, runBatch: FrozenArtifactEmbeddingBatch, signal?: AbortSignal): Promise<NeutralArtifactEmbeddingMaterialization>;