@world-engines/tmw 0.1.0-alpha.0

package/dist/compiler-release-authority.d.ts

@@ -0,0 +1,212 @@
+import { type CompileTargetProfile } from "./compile-target-profile.js";
+import { type CompilerCompatibilityCandidate, type CompilerCompatibilityFixtureFailure, type CompilerCompatibilityFixturePass } from "./compiler-compatibility-gate.js";
+import { type CompilerStageCache, type CompilerStageCacheEntry } from "./compiler-stage-cache.js";
+import { type CompilerStageRegistry } from "./compiler-stage-registry.js";
+import { type NeutralSourceCompilerReceipt, type NeutralSourceDerivedObject } from "./neutral-source-compiler.js";
+import { type NeutralSourceCaptureWitness, type NeutralSourceCompileInput } from "@world-engines/scenario-author-source";
+export declare const COMPILER_RELEASE_AUTHORITY_SCHEMA_VERSION: 1;
+export type CompilerReleaseOperationKind = "evaluate_candidate" | "promote_candidate" | "reject_candidate" | "rollback_active" | "rebuild_captured_artifact";
+export interface CompilerReleaseIdentity {
+    readonly compiler_release: string;
+    readonly target_profile: CompileTargetProfile;
+    readonly target_profile_sha256: string;
+}
+export interface CompilerReleaseStoreSnapshot {
+    readonly active: CompilerReleaseIdentity | null;
+    readonly previous_active: CompilerReleaseIdentity | null;
+}
+export interface CompilerReleaseStore {
+    read(): Promise<CompilerReleaseStoreSnapshot>;
+    writeOnce(expected: CompilerReleaseStoreSnapshot, next: CompilerReleaseStoreSnapshot): Promise<"stored" | "already_present">;
+}
+export type CompilerReleaseSnapshotLoader = () => Promise<unknown>;
+export interface CompilerReleaseAuthoritySnapshot extends CompilerReleaseStoreSnapshot {
+    readonly schema_version: typeof COMPILER_RELEASE_AUTHORITY_SCHEMA_VERSION;
+    readonly revision: number;
+}
+export interface CompilerReleaseAuthorityTransport {
+    request(input: Readonly<{
+        method: "GET" | "POST";
+        path: string;
+        body?: unknown;
+    }>): Promise<Readonly<{
+        status: number;
+        body: unknown;
+    }>>;
+}
+/**
+ * Browser 与 Node 生产消费者共用的只读 authority adapter。唯一状态来自调用方
+ * 注入的 Edge readback；adapter 不缓存、不初始化 active，也不能执行 promotion。
+ */
+export declare class ReadbackCompilerReleaseStore implements CompilerReleaseStore {
+    #private;
+    constructor(load: CompilerReleaseSnapshotLoader);
+    read(): Promise<CompilerReleaseStoreSnapshot>;
+    writeOnce(): Promise<"stored" | "already_present">;
+}
+export declare class RemoteCompilerReleaseAuthority {
+    #private;
+    constructor(transport: CompilerReleaseAuthorityTransport, currentPath?: string);
+    read(): Promise<CompilerReleaseAuthoritySnapshot>;
+    readOperation(operationId: string): Promise<CompilerReleaseOperationReceipt | null>;
+    apply(kind: "promote" | "rollback", expectedRevision: number, receipt: CompilerReleaseOperationReceipt): Promise<CompilerReleaseAuthoritySnapshot>;
+}
+export interface PromotePersistedCompilerReleaseCandidateInput extends EvaluateCompilerReleaseCandidateInput {
+    readonly authority: RemoteCompilerReleaseAuthority;
+}
+/**
+ * 生产 promotion：先从唯一 Edge authority 做 operation readback；未提交时在冻结快照上
+ * 执行完整 corpus KAT，再把完整 receipt 交给 Edge CAS。网络结果不确定时以同一
+ * operation_id 重试会先读回 receipt，不会重复推进 pointer。
+ */
+export declare function promotePersistedCompilerReleaseCandidate(input: PromotePersistedCompilerReleaseCandidateInput): Promise<CompilerReleasePromotionOutcome>;
+export interface RollbackPersistedCompilerReleaseInput {
+    readonly operation_id: string;
+    readonly authority: RemoteCompilerReleaseAuthority;
+    readonly live_store: CompilerReleaseLiveStore;
+    readonly corpus_digest: string;
+}
+export declare function rollbackPersistedCompilerRelease(input: RollbackPersistedCompilerReleaseInput): Promise<CompilerReleaseOperationReceipt>;
+export interface CompilerReleaseAuthorSourceSnapshot {
+    readonly source_bytes: Uint8Array;
+    readonly source_sha256: string;
+    readonly manifest_sha256: string;
+    readonly head_digest: string;
+    readonly source_revision: number;
+    readonly author_operation_count: number;
+}
+export interface CompilerReleaseAuthorSourceIdentity {
+    readonly source_sha256: string;
+    readonly manifest_sha256: string;
+    readonly head_digest: string;
+    readonly source_revision: number;
+    readonly author_operation_count: number;
+}
+export interface CompilerReleaseLiveStore {
+    snapshot(): Promise<CompilerReleaseAuthorSourceSnapshot>;
+    mutateWorkingProjection(mutator: (bytes: Uint8Array) => Uint8Array): Promise<void>;
+}
+export interface CompilerReleaseDerivedStore {
+    read(objectId: string): Promise<Uint8Array | null>;
+    writeOnce(objectId: string, bytes: Uint8Array): Promise<"stored" | "already_present">;
+    delete(objectId: string): Promise<void>;
+}
+export interface CompilerReleaseClearableCache extends CompilerStageCache {
+    clear(): Promise<void>;
+    keys(): Promise<readonly string[]>;
+}
+export interface CompilerReleaseUnknownContentWitness {
+    readonly kind: string;
+    readonly path: string;
+    readonly sha256: string;
+}
+export interface CompilerReleaseCapturedBuild {
+    readonly operation_id: string;
+    readonly source: NeutralSourceCompileInput;
+    readonly target_profile: CompileTargetProfile;
+    readonly target_profile_sha256: string;
+}
+export interface CompilerReleaseRebuildResult {
+    readonly ok: true;
+    readonly operation_id: string;
+    readonly compiler_release: string;
+    readonly target_profile_sha256: string;
+    readonly source_manifest_sha256: string;
+    readonly receipt: NeutralSourceCompilerReceipt;
+    readonly derived_objects: readonly NeutralSourceDerivedObject[];
+    readonly artifact_digest: string;
+    readonly witness_digest: string;
+    readonly cache_keys: readonly string[];
+}
+export interface CompilerReleaseOperationReceiptCore {
+    readonly receipt_schema_version: typeof COMPILER_RELEASE_AUTHORITY_SCHEMA_VERSION;
+    readonly operation_id: string;
+    readonly operation_kind: CompilerReleaseOperationKind;
+    readonly corpus_digest: string;
+    readonly candidate: CompilerReleaseIdentity;
+    readonly active_before: CompilerReleaseIdentity | null;
+    readonly active_after: CompilerReleaseIdentity | null;
+    readonly previous_active: CompilerReleaseIdentity | null;
+    readonly source_before: CompilerReleaseAuthorSourceIdentity;
+    readonly source_after: CompilerReleaseAuthorSourceIdentity;
+    readonly fixture_passes: readonly CompilerCompatibilityFixturePass[];
+    readonly fixture_failures: readonly CompilerCompatibilityFixtureFailure[];
+    readonly unknown_content_witnesses: readonly CompilerReleaseUnknownContentWitness[];
+}
+export interface CompilerReleaseOperationReceipt extends CompilerReleaseOperationReceiptCore {
+    readonly receipt_sha256: string;
+}
+export type CompilerReleasePromotionOutcome = {
+    readonly promotable: true;
+    readonly switched: boolean;
+    readonly receipt: CompilerReleaseOperationReceipt;
+} | {
+    readonly promotable: false;
+    readonly switched: false;
+    readonly receipt: CompilerReleaseOperationReceipt;
+};
+export interface EvaluateCompilerReleaseCandidateInput {
+    readonly operation_id: string;
+    readonly candidate: CompilerCompatibilityCandidate;
+    readonly corpus_value: unknown;
+    readonly load_fixture: (relativePath: string) => Promise<Uint8Array>;
+    readonly live_store: CompilerReleaseLiveStore;
+}
+export interface PromoteCompilerReleaseCandidateInput extends EvaluateCompilerReleaseCandidateInput {
+    readonly store: CompilerReleaseStore;
+}
+export interface RollbackCompilerReleaseInput {
+    readonly operation_id: string;
+    readonly store: CompilerReleaseStore;
+    readonly live_store: CompilerReleaseLiveStore;
+    readonly corpus_digest: string;
+}
+export interface CaptureCompilerReleaseBuildInput {
+    readonly operation_id: string;
+    readonly witness: NeutralSourceCaptureWitness;
+    readonly live_store: CompilerReleaseLiveStore;
+    readonly target_profile: CompileTargetProfile;
+}
+export interface RebuildCompilerReleaseArtifactInput {
+    readonly captured: CompilerReleaseCapturedBuild;
+    readonly registry: CompilerStageRegistry;
+    readonly cache: CompilerReleaseClearableCache;
+    readonly derived_store: CompilerReleaseDerivedStore;
+    readonly live_store: CompilerReleaseLiveStore;
+    readonly object_id: string;
+}
+export declare class InMemoryCompilerReleaseStore implements CompilerReleaseStore {
+    #private;
+    constructor(initial?: CompilerReleaseStoreSnapshot);
+    read(): Promise<CompilerReleaseStoreSnapshot>;
+    writeOnce(expected: CompilerReleaseStoreSnapshot, next: CompilerReleaseStoreSnapshot): Promise<"stored" | "already_present">;
+}
+export declare class MapBackedCompilerReleaseClearableCache implements CompilerReleaseClearableCache {
+    #private;
+    read(cacheKey: string): Promise<CompilerStageCacheEntry | null>;
+    writeOnce(entry: CompilerStageCacheEntry): Promise<"stored" | "already_present">;
+    delete(cacheKey: string): Promise<void>;
+    keys(): Promise<readonly string[]>;
+    clear(): Promise<void>;
+}
+export declare class InMemoryCompilerReleaseDerivedStore implements CompilerReleaseDerivedStore {
+    #private;
+    read(objectId: string): Promise<Uint8Array | null>;
+    writeOnce(objectId: string, bytes: Uint8Array): Promise<"stored" | "already_present">;
+    delete(objectId: string): Promise<void>;
+}
+export declare class FrozenCompilerReleaseLiveStore implements CompilerReleaseLiveStore {
+    #private;
+    constructor(snapshot: CompilerReleaseAuthorSourceSnapshot);
+    snapshot(): Promise<CompilerReleaseAuthorSourceSnapshot>;
+    mutateWorkingProjection(mutator: (bytes: Uint8Array) => Uint8Array): Promise<void>;
+}
+export declare function evaluateCompilerReleaseCandidate(input: EvaluateCompilerReleaseCandidateInput, activeBefore?: CompilerReleaseIdentity | null): Promise<CompilerReleasePromotionOutcome>;
+export declare function promoteCompilerReleaseCandidate(input: PromoteCompilerReleaseCandidateInput): Promise<CompilerReleasePromotionOutcome>;
+export declare function rollbackCompilerRelease(input: RollbackCompilerReleaseInput): Promise<CompilerReleaseOperationReceipt>;
+export declare function captureCompilerReleaseBuild(input: CaptureCompilerReleaseBuildInput): Promise<CompilerReleaseCapturedBuild>;
+export declare function rebuildCompilerReleaseArtifact(input: RebuildCompilerReleaseArtifactInput): Promise<CompilerReleaseRebuildResult>;
+export declare function clearAndRebuildCompilerReleaseArtifact(input: RebuildCompilerReleaseArtifactInput): Promise<CompilerReleaseRebuildResult>;
+export declare function requireActiveCompilerRelease(store: CompilerReleaseStore, expected: CompileTargetProfile): Promise<CompilerReleaseIdentity>;
+/** @deprecated 生产 caller 必须注入 Edge readback；保留导出仅为增量兼容并始终 fail-closed。 */
+export declare const defaultCompilerReleaseStore: CompilerReleaseStore;