@xemahq/agent-session-runtime 0.6.6 → 0.7.0

package/src/lib/launch-identity/compiled-session-launch-plan-store.ts

@@ -0,0 +1,178 @@
+import { requireSha256 } from './canonical-contract';
+import {
+  createCompiledSessionLaunchPlan,
+  decodeCompiledSessionLaunchPlan,
+  encodeCompiledSessionLaunchPlan,
+  hashCompiledSessionLaunchPlan,
+  type CompiledSessionLaunchPlan,
+} from './compiled-session-launch-plan';
+
+/**
+ * Storage boundary exposed to session launchers. Reads never degrade to a
+ * recompute path: a missing or corrupt plan is an explicit launch failure.
+ */
+export interface CompiledSessionLaunchPlanStore {
+  getByHash(contentHash: string): Promise<CompiledSessionLaunchPlan>;
+  putByHash(
+    contentHash: string,
+    plan: CompiledSessionLaunchPlan,
+  ): Promise<void>;
+}
+
+/**
+ * Minimal immutable byte-store seam implemented by the eventual database or
+ * object-store adapter. `create` must be atomic and must not overwrite.
+ */
+export interface ImmutableCompiledSessionLaunchPlanContentStore {
+  read(contentHash: string): Promise<string | undefined>;
+  create(contentHash: string, encodedPlan: string): Promise<boolean>;
+}
+
+export class CompiledSessionLaunchPlanMissingError extends Error {
+  override readonly name = 'CompiledSessionLaunchPlanMissingError';
+
+  constructor(readonly contentHash: string) {
+    super(`Compiled session launch plan '${contentHash}' does not exist.`);
+  }
+}
+
+export class CompiledSessionLaunchPlanAddressMismatchError extends Error {
+  override readonly name = 'CompiledSessionLaunchPlanAddressMismatchError';
+
+  constructor(
+    readonly expectedHash: string,
+    readonly actualHash: string,
+  ) {
+    super(
+      `Compiled session launch plan address '${expectedHash}' does not match its content hash '${actualHash}'.`,
+    );
+  }
+}
+
+export class CompiledSessionLaunchPlanCollisionError extends Error {
+  override readonly name = 'CompiledSessionLaunchPlanCollisionError';
+
+  constructor(readonly contentHash: string) {
+    super(
+      `Immutable content collision at compiled session launch plan '${contentHash}'.`,
+    );
+  }
+}
+
+export class CompiledSessionLaunchPlanIntegrityError extends Error {
+  override readonly name = 'CompiledSessionLaunchPlanIntegrityError';
+
+  constructor(
+    readonly contentHash: string,
+    override readonly cause: unknown,
+  ) {
+    super(
+      `Compiled session launch plan '${contentHash}' failed content verification.`,
+      { cause },
+    );
+  }
+}
+
+/**
+ * Verifies canonical bytes and content address on every read and write. This
+ * keeps corruption and impossible hash collisions observable at the storage
+ * boundary instead of passing damaged launch state to a runtime.
+ */
+export class VerifyingCompiledSessionLaunchPlanStore
+  implements CompiledSessionLaunchPlanStore
+{
+  constructor(
+    private readonly contentStore: ImmutableCompiledSessionLaunchPlanContentStore,
+  ) {}
+
+  async getByHash(contentHash: string): Promise<CompiledSessionLaunchPlan> {
+    const hash = requireSha256(contentHash, 'contentHash');
+    const encoded = await this.contentStore.read(hash);
+    if (encoded === undefined) {
+      throw new CompiledSessionLaunchPlanMissingError(hash);
+    }
+
+    try {
+      const plan = decodeCompiledSessionLaunchPlan(encoded);
+      const actualHash = hashCompiledSessionLaunchPlan(plan);
+      if (actualHash !== hash) {
+        throw new CompiledSessionLaunchPlanAddressMismatchError(
+          hash,
+          actualHash,
+        );
+      }
+      if (encodeCompiledSessionLaunchPlan(plan) !== encoded) {
+        throw new TypeError(
+          'Stored launch plan bytes are not in canonical encoding.',
+        );
+      }
+      return plan;
+    } catch (error) {
+      throw new CompiledSessionLaunchPlanIntegrityError(hash, error);
+    }
+  }
+
+  async putByHash(
+    contentHash: string,
+    plan: CompiledSessionLaunchPlan,
+  ): Promise<void> {
+    const hash = requireSha256(contentHash, 'contentHash');
+    const canonicalPlan = createCompiledSessionLaunchPlan(plan);
+    const actualHash = hashCompiledSessionLaunchPlan(canonicalPlan);
+    if (actualHash !== hash) {
+      throw new CompiledSessionLaunchPlanAddressMismatchError(hash, actualHash);
+    }
+    const encoded = encodeCompiledSessionLaunchPlan(canonicalPlan);
+
+    const existing = await this.contentStore.read(hash);
+    if (existing !== undefined) {
+      this.assertSameContent(hash, existing, encoded);
+      return;
+    }
+
+    const created = await this.contentStore.create(hash, encoded);
+    if (created) {
+      return;
+    }
+
+    const racedExisting = await this.contentStore.read(hash);
+    if (racedExisting === undefined) {
+      throw new CompiledSessionLaunchPlanIntegrityError(
+        hash,
+        new Error(
+          'Immutable content store reported an existing value but returned no content.',
+        ),
+      );
+    }
+    this.assertSameContent(hash, racedExisting, encoded);
+  }
+
+  private assertSameContent(
+    contentHash: string,
+    existing: string,
+    expected: string,
+  ): void {
+    if (existing !== expected) {
+      throw new CompiledSessionLaunchPlanCollisionError(contentHash);
+    }
+  }
+}
+
+/** Deterministic in-memory adapter for tests and process-local tooling. */
+export class InMemoryCompiledSessionLaunchPlanContentStore
+  implements ImmutableCompiledSessionLaunchPlanContentStore
+{
+  private readonly values = new Map<string, string>();
+
+  async read(contentHash: string): Promise<string | undefined> {
+    return this.values.get(contentHash);
+  }
+
+  async create(contentHash: string, encodedPlan: string): Promise<boolean> {
+    if (this.values.has(contentHash)) {
+      return false;
+    }
+    this.values.set(contentHash, encodedPlan);
+    return true;
+  }
+}