@world-engines/scenario-review-snapshot 0.0.0

package/dist/publish-attempt.d.ts

@@ -0,0 +1,118 @@
+import type { ArtifactV5, ArtifactCompilerWitnessIdentity, FrozenArtifactBundle, FrozenArtifactObjectIdentity, PublishedArtifactHead, Sha256Hex } from "./artifact.js";
+declare const frozenArtifactPrefixBrand: unique symbol;
+declare const frozenArtifactObjectKeyBrand: unique symbol;
+declare const publishOperationKeyBrand: unique symbol;
+export type FrozenArtifactPrefix = string & {
+    readonly [frozenArtifactPrefixBrand]: true;
+};
+export type FrozenArtifactObjectKey = string & {
+    readonly [frozenArtifactObjectKeyBrand]: true;
+};
+export type PublishOperationKey = string & {
+    readonly [publishOperationKeyBrand]: true;
+};
+export interface WriteOnceArtifactObject {
+    readonly key: FrozenArtifactObjectKey;
+    readonly sha256: Sha256Hex;
+    readonly size_bytes: number;
+    readonly bytes: Uint8Array;
+}
+export interface ArtifactObjectReadbackReceipt {
+    readonly key: FrozenArtifactObjectKey;
+    readonly kind: FrozenArtifactObjectIdentity["kind"];
+    readonly relative_path: string;
+    readonly media_type: string;
+    readonly sha256: Sha256Hex;
+    readonly size_bytes: number;
+}
+export type WriteOncePutResult = {
+    readonly disposition: "created";
+    readonly key: FrozenArtifactObjectKey;
+    readonly sha256: Sha256Hex;
+} | {
+    readonly disposition: "already_exists_identical";
+    readonly key: FrozenArtifactObjectKey;
+    readonly sha256: Sha256Hex;
+};
+/** 已存在但 hash/size 不同必须抛冲突，不得覆盖。 */
+export interface WriteOnceArtifactStore {
+    /** 实现必须先重算 bytes 的 hash/size，再执行 conditional create。 */
+    putIfAbsent(object: WriteOnceArtifactObject): Promise<WriteOncePutResult>;
+    readVerified(key: FrozenArtifactObjectKey, expected: Readonly<{
+        sha256: Sha256Hex;
+        size_bytes: number;
+    }>): Promise<Uint8Array>;
+}
+export interface SubmitFrozenArtifactInput {
+    readonly operation_key: PublishOperationKey;
+    readonly bundle: FrozenArtifactBundle;
+    readonly expected_previous_head_digest: Sha256Hex | null;
+}
+export interface SubmittedPublishAttempt {
+    readonly attempt_id: string;
+    readonly operation_key: PublishOperationKey;
+    readonly scenario_id: string;
+    readonly epoch: number;
+    readonly runtime_contract_hash: Sha256Hex;
+    readonly source_revision_digest: Sha256Hex;
+    readonly artifact_canonical_digest: Sha256Hex;
+    /**
+     * Parsed from the submitted witness objects after their bytes are matched
+     * against the ArtifactV5 resource identities. It is never trusted from a
+     * parallel request field or response echo.
+     */
+    readonly compiler_witness: ArtifactCompilerWitnessIdentity;
+    /** 由受信服务端从冻结对象生成，不能由 Creator 自报。 */
+    readonly review_snapshot_hash: Sha256Hex;
+    readonly review_coverage_hash: Sha256Hex;
+    readonly state: PublishAttemptState;
+    readonly object_readbacks: readonly ArtifactObjectReadbackReceipt[];
+}
+export type PublishAttemptState = "pending_review" | "claimed" | "approved" | "warning" | "rejected" | "needs_info" | "scheduled" | "published";
+export interface FinalizeApprovedArtifactInput {
+    readonly attempt_id: string;
+    readonly scenario_id: string;
+    readonly epoch: number;
+    readonly runtime_contract_hash: Sha256Hex;
+    readonly source_revision_digest: Sha256Hex;
+    readonly artifact_canonical_digest: Sha256Hex;
+    readonly expected_previous_head_digest: Sha256Hex | null;
+}
+export type FinalizeApprovedArtifactResult = {
+    readonly disposition: "published";
+    readonly head: PublishedArtifactHead;
+} | {
+    readonly disposition: "already_published_identical";
+    readonly head: PublishedArtifactHead;
+};
+export interface ResolvePublishedArtifactInput {
+    readonly scenario_id: string;
+    readonly epoch: number;
+    readonly runtime_contract_hash: Sha256Hex;
+    /** 必填；禁止退化为“当前 ScenarioRecord”。 */
+    readonly artifact_canonical_digest: Sha256Hex;
+}
+export interface ResolvedPublishedArtifact {
+    readonly artifact: ArtifactV5;
+    readonly head: PublishedArtifactHead;
+    readonly object_reader: PublishedArtifactObjectReader;
+    readonly object_readbacks: readonly ArtifactObjectReadbackReceipt[];
+}
+export interface PublishedArtifactObjectReader {
+    readonly objects: readonly FrozenArtifactObjectIdentity[];
+    /** 实现必须拒绝不属于 `objects` 的 identity。 */
+    readVerified(object: FrozenArtifactObjectIdentity): Promise<Uint8Array>;
+}
+/**
+ * 深模块接口：submit 只创建待审 attempt；approval 不发布；只有显式 finalize 才创建 head。
+ */
+export interface PublishAttemptCoordinator {
+    /** 实现进入 Interface seam 后必须立即 parse/copy bundle，且不得在 copy 前 await。 */
+    submitFrozenArtifact(input: SubmitFrozenArtifactInput): Promise<SubmittedPublishAttempt>;
+    finalizeApprovedArtifact(input: FinalizeApprovedArtifactInput): Promise<FinalizeApprovedArtifactResult>;
+    resolvePublishedArtifact(input: ResolvePublishedArtifactInput): Promise<ResolvedPublishedArtifact>;
+}
+export declare function publishOperationKey(value: string): PublishOperationKey;
+export declare function buildFrozenArtifactPrefix(scenarioId: string, canonicalDigest: Sha256Hex): FrozenArtifactPrefix;
+export declare function buildFrozenArtifactObjectKey(scenarioId: string, canonicalDigest: Sha256Hex, relativePath: string): FrozenArtifactObjectKey;
+export {};

package/dist/publish-attempt.js

@@ -0,0 +1,33 @@
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const OPERATION_KEY_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+export function publishOperationKey(value) {
+    if (!OPERATION_KEY_PATTERN.test(value))
+        throw new Error("publish_operation_key_invalid");
+    return value;
+}
+export function buildFrozenArtifactPrefix(scenarioId, canonicalDigest) {
+    const scenario = requireSegment(scenarioId, "frozen_artifact_scenario_id_invalid");
+    if (!SHA256_PATTERN.test(canonicalDigest))
+        throw new Error("frozen_artifact_digest_invalid");
+    return `scenario-releases/${encodeURIComponent(scenario)}/${canonicalDigest}`;
+}
+export function buildFrozenArtifactObjectKey(scenarioId, canonicalDigest, relativePath) {
+    const prefix = buildFrozenArtifactPrefix(scenarioId, canonicalDigest);
+    const path = requireRelativePath(relativePath);
+    return `${prefix}/${path}`;
+}
+function requireSegment(value, code) {
+    if (typeof value !== "string" || value.length === 0 || value.trim() !== value || value.normalize("NFC") !== value) {
+        throw new Error(code);
+    }
+    return value;
+}
+function requireRelativePath(value) {
+    const path = requireSegment(value, "frozen_artifact_object_relative_path_invalid");
+    if (path.startsWith("/")
+        || path.endsWith("/")
+        || path.includes("\\")
+        || path.split("/").some((part) => part.length === 0 || part === "." || part === ".."))
+        throw new Error("frozen_artifact_object_relative_path_invalid");
+    return path;
+}

package/dist/server-bound-view-compiler.d.ts

@@ -0,0 +1,26 @@
+import { type CompileTargetProfile } from "@world-engines/tmw";
+import { type ProjectFileTree } from "@world-engines/chatplay-vite-plugin/project-sync";
+import type { ServerBoundViewCompiler, ServerBoundViewProjectCodec } from "./bound-view-freeze.js";
+/**
+ * Sandbox Node build worker 的唯一运行时依赖。gzip-tar codec 必须来自同一受信
+ * worker image；snapshot 包不依赖 creator-editor/browser implementation。
+ */
+export interface SandboxNodeGzipTarCodec {
+    pack(project: ProjectFileTree): Promise<Uint8Array>;
+    unpack(bytes: Uint8Array): Promise<ProjectFileTree>;
+}
+export interface CreateSandboxNodeBoundViewCompilerOptions {
+    /** 已经由 worker admission 选定的 active compiler profile。 */
+    readonly target_profile: CompileTargetProfile;
+    readonly gzip_tar: SandboxNodeGzipTarCodec;
+}
+export interface SandboxNodeBoundViewCompiler {
+    readonly codec: ServerBoundViewProjectCodec<ProjectFileTree>;
+    readonly compiler: ServerBoundViewCompiler<ProjectFileTree>;
+}
+/**
+ * 给 server build worker 的实际 factory：SVP decode 是固定生产 codec，TMW
+ * registry/cache/compiler 也固定；只有 worker image 的 gzip-tar implementation
+ * 需要注入，保证 source pack/unpack 是同一可信 codec。
+ */
+export declare function createSandboxNodeBoundViewCompiler(options: CreateSandboxNodeBoundViewCompilerOptions): SandboxNodeBoundViewCompiler;

package/dist/server-bound-view-compiler.js

@@ -0,0 +1,34 @@
+import { InMemoryCompilerStageCache, buildCurrentTmw3NeutralCompilerStageRegistry, compileNeutralScenarioSource, } from "@world-engines/tmw";
+import { decodeSvp, } from "@world-engines/chatplay-vite-plugin/project-sync";
+import { materializeNeutralArtifactCompilation, } from "./neutral-artifact-assembler.js";
+/**
+ * 给 server build worker 的实际 factory：SVP decode 是固定生产 codec，TMW
+ * registry/cache/compiler 也固定；只有 worker image 的 gzip-tar implementation
+ * 需要注入，保证 source pack/unpack 是同一可信 codec。
+ */
+export function createSandboxNodeBoundViewCompiler(options) {
+    const stages = buildCurrentTmw3NeutralCompilerStageRegistry();
+    const cache = new InMemoryCompilerStageCache();
+    const codec = Object.freeze({
+        decode_svp(bytes) {
+            return decodeSvp(bytes);
+        },
+        async pack_gzip_tar(project) {
+            const packed = await options.gzip_tar.pack(project);
+            if (!(packed instanceof Uint8Array) || packed.byteLength === 0) {
+                throw new Error("server_bound_view_gzip_tar_pack_invalid");
+            }
+            return packed.slice();
+        },
+    });
+    const compiler = Object.freeze({
+        async compile(source) {
+            const outcome = await compileNeutralScenarioSource(source, options.target_profile, stages, cache);
+            if (!outcome.ok) {
+                throw new Error(`server_bound_view_compile_failed:${outcome.diagnostics.map((item) => item.code).join(",")}`);
+            }
+            return await materializeNeutralArtifactCompilation(source, options.target_profile, outcome, async (bytes) => await options.gzip_tar.unpack(bytes));
+        },
+    });
+    return Object.freeze({ codec, compiler });
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,5 @@
+import type { JsonValue, ScenarioReviewFragment, ScenarioReviewRecord, ScenarioReviewSnapshot, ScenarioReviewSnapshotInput, ScenarioReviewSnapshotLimits } from "./types.js";
+export declare const DEFAULT_SCENARIO_REVIEW_SNAPSHOT_LIMITS: ScenarioReviewSnapshotLimits;
+export declare function stableRelationId(edge: JsonValue): string;
+export declare function buildScenarioReviewSnapshot(rawInput: ScenarioReviewSnapshotInput, rawLimits?: Partial<ScenarioReviewSnapshotLimits>): ScenarioReviewSnapshot;
+export declare function reconstructRecordPayload(record: ScenarioReviewRecord, fragments: readonly ScenarioReviewFragment[]): JsonValue;