@hraness/oh 0.4.1 → 0.4.2

package/src/memory-authority-platform.ts

@@ -0,0 +1,133 @@
+import { Context, Effect, Layer } from "effect";
+import { safeCode } from "./canonical";
+import { OH_OPERATION_MAX_BYTES_V1 } from "./operation";
+import { OhConflictError, OhIntegrityError, OhProfileError,
+  type OhHeadV1, type OhStoreV1 } from "./store";
+import {
+  authorityId, bindingFor, continuationKeyV2, createOhMemoryAgentV2WithRuntime,
+  createOhMemoryRuntimeV2, immutableClone, parseMemoryAuthorityHead,
+  resolveExtractors, resolveNominationRoutes, resolveProgramsV2,
+  type OhMemoryAuthorityOptionsV1,
+} from "./memory-core";
+
+export type MemoryFailure = Readonly<{
+  _tag: "MemoryConflict" | "MemoryIntegrity" | "MemoryProfile" | "MemoryValidation" | "MemoryCapacity" | "MemoryForeign";
+  cause: unknown;
+}>;
+
+export function memoryFailure(cause: unknown): MemoryFailure {
+  return { _tag: cause instanceof OhConflictError ? "MemoryConflict"
+    : cause instanceof OhIntegrityError ? "MemoryIntegrity"
+    : cause instanceof OhProfileError ? "MemoryProfile"
+    : cause instanceof TypeError ? "MemoryValidation"
+    : cause instanceof RangeError ? "MemoryCapacity" : "MemoryForeign", cause };
+}
+
+/** Validation may reject hostile values; unrelated generator defects are not caught. */
+export function memoryValue<A>(evaluate: () => A): Effect.Effect<A, MemoryFailure> {
+  return Effect.try({ try: evaluate, catch: memoryFailure });
+}
+
+function memoryCall<A>(operation: () => Promise<A>): Effect.Effect<A, MemoryFailure> {
+  return Effect.tryPromise({ try: operation, catch: memoryFailure });
+}
+
+function readStore(store: OhStoreV1) {
+  return {
+    binding: store.binding,
+    head: memoryCall(() => store.head()),
+    snapshot: (options: Parameters<OhStoreV1["snapshot"]>[0]) => memoryCall(() => store.snapshot(options)),
+    changesSince: (from: Parameters<OhStoreV1["changesSince"]>[0], options: Parameters<OhStoreV1["changesSince"]>[1]) =>
+      memoryCall(() => store.changesSince(from, options)),
+  };
+}
+
+/** Canonical commit is provided only to the trusted host authority composition. */
+export class CanonicalMemoryStore extends Context.Tag("@hraness/oh/CanonicalMemoryStore")<
+  CanonicalMemoryStore, ReturnType<typeof canonicalStorePort>
+>() {}
+
+function canonicalStorePort(store: OhStoreV1) {
+  return { ...readStore(store),
+    commit: (input: Parameters<OhStoreV1["commit"]>[0]) => memoryCall(() => store.commit(input)),
+  };
+}
+
+export type CanonicalMemoryStoreService = ReturnType<typeof canonicalStorePort>;
+
+/** The host adoption program borrows only the working closure read capability. */
+export class WorkingMemorySource extends Context.Tag("@hraness/oh/WorkingMemorySource")<
+  WorkingMemorySource, {
+    readonly exportDependencyClosure: (input: Parameters<OhStoreV1["exportDependencyClosure"]>[0]) =>
+      Effect.Effect<Awaited<ReturnType<OhStoreV1["exportDependencyClosure"]>>, MemoryFailure>;
+  }
+>() {}
+
+function prepareAuthority(options: OhMemoryAuthorityOptionsV1) {
+  const maximumCanonicalOperationBytes = options.maximumCanonicalOperationBytes ?? OH_OPERATION_MAX_BYTES_V1;
+  if (!Number.isSafeInteger(maximumCanonicalOperationBytes) || maximumCanonicalOperationBytes < 1
+    || maximumCanonicalOperationBytes > OH_OPERATION_MAX_BYTES_V1) {
+    throw new TypeError("Invalid canonical memory operation byte bound.");
+  }
+  const memoryActorId = safeCode(options.actorId, 128);
+  const adoptionActorId = safeCode(options.adoptionActorId, 128);
+  if (memoryActorId === null || adoptionActorId === null) throw new TypeError("Invalid host-bound memory authority actor ID.");
+  const canonicalStore = options.canonical.store;
+  const workingStore = options.working.store;
+  const canonicalAuthorityId = authorityId(options.canonical.authorityId);
+  const workingAuthorityId = authorityId(options.working.authorityId);
+  if (canonicalAuthorityId === workingAuthorityId) throw new OhProfileError("Working and canonical memory must be distinct physical authorities.");
+  const canonicalBinding = bindingFor(canonicalStore, options.canonical.expectedBindingSha256, "canonical");
+  const workingBinding = bindingFor(workingStore, options.working.expectedBindingSha256, "working");
+  const initialCanonicalHead = parseMemoryAuthorityHead(options.canonical.expectedHead, "initial canonical");
+  const workingCodecs = options.working.codecs;
+  const explainCapabilityLifetimeMs = options.explainCapabilityLifetimeMs;
+  const monotonicNow = options.monotonicNow;
+  const now = options.now;
+  const continuationKey = continuationKeyV2(options.continuationKey);
+  const programs = Object.freeze([...resolveProgramsV2(options.programs).values()].map((program) =>
+    immutableClone({ evaluation: program.evaluation, maximumPageBytes: program.maximumPageBytes,
+      maximumRows: program.maximumRows, pageSize: program.pageSize, parameters: program.parameters,
+      programId: program.programId, purpose: program.purpose, query: program.query,
+      rulePack: program.rulePack, v: 2 as const })));
+  const extractors = resolveExtractors(options.extractors ?? []);
+  const nominationRoutes = Object.freeze([...resolveNominationRoutes(options.nominationRoutes ?? []).values()]);
+  const runtime = createOhMemoryRuntimeV2(options);
+  const createAgentAt = (expectedHead: OhHeadV1) => memoryCall(() => createOhMemoryAgentV2WithRuntime({
+    actorId: memoryActorId,
+    canonical: { authorityId: canonicalAuthorityId, expectedBindingSha256: canonicalBinding.bindingSha256,
+      expectedHead, store: canonicalStore },
+    continuationKey,
+    ...(explainCapabilityLifetimeMs === undefined ? {} : { explainCapabilityLifetimeMs }),
+    extractors,
+    ...(monotonicNow === undefined ? {} : { monotonicNow }),
+    nominationRoutes,
+    ...(now === undefined ? {} : { now }),
+    programs,
+    working: { authorityId: workingAuthorityId, codecs: workingCodecs,
+      expectedBindingSha256: workingBinding.bindingSha256, store: workingStore },
+  }, runtime));
+  return { adoptionActorId, canonicalAuthorityId, workingAuthorityId, canonicalBinding, workingBinding,
+    initialCanonicalHead, maximumCanonicalOperationBytes, createAgentAt,
+    routesById: new Map(nominationRoutes.map((route) => [route.nominationId, route])),
+    canonical: canonicalStorePort(canonicalStore),
+    working: { exportDependencyClosure: (input: Parameters<OhStoreV1["exportDependencyClosure"]>[0]) =>
+      memoryCall(() => workingStore.exportDependencyClosure(input)) },
+  };
+}
+
+export class MemoryAuthorityConfig extends Context.Tag("@hraness/oh/MemoryAuthorityConfig")<
+  MemoryAuthorityConfig, Omit<ReturnType<typeof prepareAuthority>, "canonical" | "working">
+>() {}
+
+/** Preparation captures caller-owned options before the first foreign wait. Stores
+ * are borrowed; these Layers cannot close or purge either physical authority. */
+export function memoryAuthorityLive(options: OhMemoryAuthorityOptionsV1):
+  Layer.Layer<MemoryAuthorityConfig | CanonicalMemoryStore | WorkingMemorySource, MemoryFailure> {
+  return Layer.unwrapEffect(memoryValue(() => prepareAuthority(options)).pipe(Effect.map(prepared => {
+    const { canonical, working, ...config } = prepared;
+    return Layer.mergeAll(Layer.succeed(MemoryAuthorityConfig, config),
+      Layer.succeed(CanonicalMemoryStore, canonical),
+      Layer.succeed(WorkingMemorySource, working));
+  })));
+}

package/src/memory-authority-program.ts

@@ -0,0 +1,309 @@
+import { Cause, Effect, Exit, Option } from "effect";
+import { canonicalJson, canonicalSha256, isPlainRecord, hasExactKeys } from "./canonical";
+import { canonicalKnowledgeGraphChangesV1, type KnowledgeGraphChangeV1 } from "./graph";
+import { parseOhOperationV1 } from "./operation";
+import { OH_DEPENDENCY_CLOSURE_LIMITS_V1, OhConflictError, OhIntegrityError, OhProfileError,
+  parseOhHeadRefV1, parseOhHeadV1, type OhHeadV1, type OhStoreBindingV1 } from "./store";
+import { OH_MEMORY_LIMITS_V1, OH_MEMORY_AUTHORITY_LIMITS_V1, immutableClone, exactHead, headRef,
+  parseDetachedStoreSnapshot, datasetForSnapshot, parseMemoryAuthorityHead, detachCanonicalData,
+  parseCanonicalAdvanceRequest, parseAdoptionRequest, canonicalAdvanceReceipt, adoptionReceipt,
+  adoptionDifferences, unauthorizedAdoptionDifferences, assertAdoptionSnapshotCapacity, adoptionConflict,
+  type LaneSnapshot, type OhMemoryCanonicalAdvanceReceiptV1, type OhMemoryAdoptionReceiptV1,
+  type OhMemoryAdoptionConflictEntryV1 } from "./memory-core";
+import { CanonicalMemoryStore, WorkingMemorySource, MemoryAuthorityConfig, memoryValue, memoryFailure, type CanonicalMemoryStoreService,
+  type MemoryFailure } from "./memory-authority-platform";
+
+type CanonicalAuthority = Readonly<{ authorityId: string; binding: OhStoreBindingV1;
+  store: CanonicalMemoryStoreService }>;
+
+function readLane(authority: CanonicalAuthority, lane: "canonical", expectedHead: OhHeadV1):
+  Effect.Effect<LaneSnapshot, MemoryFailure> {
+  return Effect.gen(function* () {
+    const head = immutableClone(expectedHead);
+    const returnedSnapshot = yield* authority.store.snapshot({
+      head: { operationSha256: head.operationSha256, sequence: head.sequence },
+      maximumRecords: OH_MEMORY_LIMITS_V1.maximumRecordsPerLane,
+    });
+    return yield* memoryValue(() => {
+      const parsed = parseDetachedStoreSnapshot(returnedSnapshot, `The ${lane} store`, head, authority.binding.spaceId);
+      const projected = datasetForSnapshot(authority.binding, parsed.snapshot, parsed.projectionSnapshot);
+      return Object.freeze({ authorityId: authority.authorityId, binding: authority.binding,
+        dataset: projected.dataset, lane, projectionSnapshot: projected.projectionSnapshot, snapshot: parsed.snapshot });
+    });
+  });
+}
+
+function proveCanonicalDescendant(
+  authority: CanonicalAuthority,
+  priorHead: OhHeadV1,
+  nextHead: OhHeadV1,
+  requiredFirstHead?: OhHeadV1,
+): Effect.Effect<LaneSnapshot, MemoryFailure> {
+  return Effect.gen(function* () {
+    if (nextHead.sequence <= priorHead.sequence) {
+      return yield* Effect.fail(memoryFailure(new OhConflictError("The next canonical memory head is not a descendant of the current pin.")));
+    }
+    const distance = nextHead.sequence - priorHead.sequence;
+    if (distance > OH_MEMORY_AUTHORITY_LIMITS_V1.canonicalAdvanceOperations
+      || Math.ceil(distance / OH_MEMORY_AUTHORITY_LIMITS_V1.canonicalChangeFeedPage)
+        > OH_MEMORY_AUTHORITY_LIMITS_V1.canonicalAdvancePages) {
+      return yield* Effect.fail(memoryFailure(new RangeError("The canonical memory advance exceeds its total proof bound; advance in host-reviewed chunks.")));
+    }
+    const through = headRef(nextHead);
+    let cursor = headRef(priorHead);
+    let pageCount = 0;
+    let reachedHead: OhHeadV1 | null = null;
+    let firstHead: OhHeadV1 | null = null;
+    while (cursor.sequence < through.sequence) {
+      if (pageCount >= OH_MEMORY_AUTHORITY_LIMITS_V1.canonicalAdvancePages) {
+        return yield* Effect.fail(memoryFailure(new RangeError("The canonical memory advance exceeded its page proof bound; advance in host-reviewed chunks.")));
+      }
+      pageCount += 1;
+      const remaining = through.sequence - cursor.sequence;
+      const limit = Math.min(remaining, OH_MEMORY_AUTHORITY_LIMITS_V1.canonicalChangeFeedPage);
+      const page = yield* authority.store.changesSince(cursor, { limit, through });
+      const returnedData = (yield* memoryValue(() => detachCanonicalData(
+        page,
+        "The canonical change-feed page",
+        OH_MEMORY_AUTHORITY_LIMITS_V1.canonicalChangeFeedPageBytes,
+      ))).value;
+      const returned = returnedData as Record<string, unknown>;
+      if (!isPlainRecord(returned) || !hasExactKeys(returned,
+        ["from", "hasMore", "operations", "through", "to", "v"])
+        || returned.v !== 1 || typeof returned.hasMore !== "boolean"
+        || !Array.isArray(returned.operations) || returned.operations.length > limit) {
+        return yield* Effect.fail(memoryFailure(new OhIntegrityError("The canonical change feed returned an invalid page envelope.")));
+      }
+      const from = parseOhHeadRefV1(returned.from);
+      const returnedThrough = parseOhHeadV1(returned.through);
+      const returnedTo = parseOhHeadRefV1(returned.to);
+      if (from === null || returnedThrough === null || returnedTo === null
+        || canonicalJson(from) !== canonicalJson(cursor)
+        || !exactHead(returnedThrough, nextHead)) {
+        return yield* Effect.fail(memoryFailure(new OhIntegrityError("The canonical change feed changed its pinned bounds.")));
+      }
+      let reached = cursor;
+      for (const value of returned.operations) {
+        const operation = parseOhOperationV1(value);
+        if (operation === null || operation.spaceId !== authority.binding.spaceId
+          || operation.sequence !== reached.sequence + 1
+          || operation.parentOperationSha256 !== reached.operationSha256) {
+          return yield* Effect.fail(memoryFailure(new OhIntegrityError("The canonical change feed contains a gap or different authority.")));
+        }
+        reached = Object.freeze({ operationSha256: operation.operationSha256,
+          sequence: operation.sequence });
+        reachedHead = immutableClone({ generation: operation.sequence,
+          graphRevisionSha256: operation.graphRevisionSha256,
+          operationSha256: operation.operationSha256, recordsSha256: operation.recordsSha256,
+          sequence: operation.sequence, v: 1 });
+        firstHead ??= reachedHead;
+      }
+      if (canonicalJson(reached) !== canonicalJson(returnedTo)
+        || (returned.hasMore && returned.operations.length === 0)
+        || (returned.hasMore && reached.sequence >= through.sequence)
+        || reached.sequence > through.sequence
+        || (!returned.hasMore && canonicalJson(reached) !== canonicalJson(through))) {
+        return yield* Effect.fail(memoryFailure(new OhIntegrityError("The canonical change feed did not prove the requested descendant.")));
+      }
+      cursor = reached;
+    }
+    if (reachedHead === null || !exactHead(reachedHead, nextHead)) {
+      return yield* Effect.fail(memoryFailure(new OhIntegrityError("The canonical change feed did not prove the requested full head.")));
+    }
+    if (requiredFirstHead !== undefined
+      && (firstHead === null || !exactHead(firstHead, requiredFirstHead))) {
+      return yield* Effect.fail(memoryFailure(new OhIntegrityError("The returned adoption operation is not on the current canonical path.")));
+    }
+    return yield* readLane(authority, "canonical", nextHead);
+  });
+}
+
+/** One FIFO for trusted host changes; agent calls retain their captured immutable pin.
+ * After admission the operation retains its permit through actual foreign settlement
+ * and pin publication. Native commit/CAS remains authoritative; there is no retry. */
+export const makeMemoryAuthority = Effect.gen(function* () {
+  const { initialCanonicalHead, createAgentAt, canonicalAuthorityId, workingAuthorityId,
+    canonicalBinding, workingBinding, routesById, adoptionActorId, maximumCanonicalOperationBytes } = yield* MemoryAuthorityConfig;
+  const canonicalStore = yield* CanonicalMemoryStore;
+  const workingStore = yield* WorkingMemorySource;
+  const hostOrder = yield* Effect.makeSemaphore(1);
+  let activeCanonicalHead = initialCanonicalHead;
+  let activeAgent = yield* createAgentAt(activeCanonicalHead);
+  const canonicalAuthority = Object.freeze({ authorityId: canonicalAuthorityId, binding: canonicalBinding, store: canonicalStore });
+  const installCanonicalHead = (head: OhHeadV1) => Effect.gen(function* () {
+    const nextAgent = yield* createAgentAt(head);
+    // Publish both references together only after the next snapshot is verified.
+    activeAgent = nextAgent;
+    activeCanonicalHead = immutableClone(head);
+  });
+  const readPhysicalCanonicalHead = () => canonicalStore.head.pipe(
+    Effect.flatMap(head => memoryValue(() => parseMemoryAuthorityHead(head, "physical canonical"))));
+  const advanceCanonical = (request: ReturnType<typeof parseCanonicalAdvanceRequest>): Effect.Effect<OhMemoryCanonicalAdvanceReceiptV1, MemoryFailure> =>
+    hostOrder.withPermits(1)(Effect.uninterruptible(Effect.gen(function* () {
+      const priorHead = activeCanonicalHead;
+      if (!exactHead(request.expectedHead, priorHead)) {
+        return yield* Effect.fail(memoryFailure(new OhConflictError("The expected canonical memory head does not match the current pin.")));
+      }
+      if (exactHead(request.nextHead, priorHead)) {
+        return canonicalAdvanceReceipt(canonicalAuthorityId, canonicalBinding.bindingSha256,
+          priorHead, priorHead, "unchanged");
+      }
+      yield* proveCanonicalDescendant(canonicalAuthority, priorHead, request.nextHead);
+      yield* installCanonicalHead(request.nextHead);
+      return canonicalAdvanceReceipt(canonicalAuthorityId, canonicalBinding.bindingSha256,
+        priorHead, request.nextHead, "advanced");
+    })));
+
+  const adoptNomination = (request: ReturnType<typeof parseAdoptionRequest>): Effect.Effect<OhMemoryAdoptionReceiptV1, MemoryFailure> =>
+    hostOrder.withPermits(1)(Effect.uninterruptible(Effect.gen(function* () {
+      const route = routesById.get(request.nomination.nominationId);
+      if (route === undefined || route.destinationPurpose !== request.nomination.destinationPurpose) {
+        return yield* Effect.fail(memoryFailure(new OhProfileError("The memory nomination is not bound to this adoption route.")));
+      }
+      if (request.nomination.source.authorityId !== workingAuthorityId
+        || request.nomination.source.bindingSha256 !== workingBinding.bindingSha256
+        || request.nomination.closure.binding.bindingSha256 !== workingBinding.bindingSha256) {
+        return yield* Effect.fail(memoryFailure(new OhProfileError("The memory nomination is not from the bound working authority.")));
+      }
+      const returnedReexport = yield* workingStore.exportDependencyClosure({
+        head: headRef(request.nomination.source.head),
+        maximumRecords: OH_DEPENDENCY_CLOSURE_LIMITS_V1.records,
+        roots: request.nomination.closure.roots,
+      });
+      const reexported = yield* memoryValue(() => detachCanonicalData(returnedReexport, "The working re-exported nomination",
+        OH_DEPENDENCY_CLOSURE_LIMITS_V1.bytes));
+      if (reexported.canonical !== canonicalJson(request.nomination.closure)) {
+        return yield* Effect.fail(memoryFailure(new OhIntegrityError("The working authority did not re-export the nominated closure exactly.")));
+      }
+
+      const priorHead = activeCanonicalHead;
+      const physicalHead = yield* readPhysicalCanonicalHead();
+      const replacementConflictsAt = (currentLane: LaneSnapshot): Effect.Effect<readonly OhMemoryAdoptionConflictEntryV1[], MemoryFailure> => Effect.gen(function* () {
+        if (request.replacements.length === 0) return [];
+        const reviewedLane = exactHead(request.expectedCanonicalHead, currentLane.snapshot.head)
+          ? currentLane
+          : yield* readLane(canonicalAuthority, "canonical", request.expectedCanonicalHead);
+        return unauthorizedAdoptionDifferences(reviewedLane.snapshot, currentLane.snapshot,
+          request.nomination.closure.records, request.replacements);
+      });
+      if (!exactHead(physicalHead, priorHead)) {
+        const physicalLane = yield* proveCanonicalDescendant(canonicalAuthority, priorHead, physicalHead);
+        const physicalDifferences = adoptionDifferences(physicalLane.snapshot,
+          request.nomination.closure.records);
+        if (physicalDifferences.length === 0) {
+          const replacementConflicts = yield* replacementConflictsAt(physicalLane);
+          if (replacementConflicts.length > 0) {
+            return yield* Effect.fail(memoryFailure(adoptionConflict(request.expectedCanonicalHead, physicalHead, replacementConflicts)));
+          }
+          yield* installCanonicalHead(physicalHead);
+          return adoptionReceipt(adoptionActorId, canonicalAuthorityId,
+            canonicalBinding.bindingSha256, request.nomination.nominationSha256, null,
+            priorHead, physicalHead, "already-present");
+        }
+        return yield* Effect.fail(memoryFailure(adoptionConflict(request.expectedCanonicalHead, physicalHead, physicalDifferences)));
+      }
+
+      const lane = yield* readLane(canonicalAuthority, "canonical", priorHead);
+      const differences = adoptionDifferences(lane.snapshot, request.nomination.closure.records);
+      if (!exactHead(request.expectedCanonicalHead, priorHead)) {
+        if (differences.length === 0) {
+          const replacementConflicts = yield* replacementConflictsAt(lane);
+          if (replacementConflicts.length > 0) {
+            return yield* Effect.fail(memoryFailure(adoptionConflict(request.expectedCanonicalHead, priorHead, replacementConflicts)));
+          }
+          return adoptionReceipt(adoptionActorId, canonicalAuthorityId,
+            canonicalBinding.bindingSha256, request.nomination.nominationSha256, null,
+            priorHead, priorHead, "already-present");
+        }
+        return yield* Effect.fail(memoryFailure(adoptionConflict(request.expectedCanonicalHead, priorHead, differences)));
+      }
+      if (differences.length === 0) {
+        const replacementConflicts = yield* replacementConflictsAt(lane);
+        if (replacementConflicts.length > 0) {
+          return yield* Effect.fail(memoryFailure(adoptionConflict(request.expectedCanonicalHead, priorHead, replacementConflicts)));
+        }
+        return adoptionReceipt(adoptionActorId, canonicalAuthorityId,
+          canonicalBinding.bindingSha256, request.nomination.nominationSha256, null,
+          priorHead, priorHead, "already-present");
+      }
+      const unauthorized = unauthorizedAdoptionDifferences(lane.snapshot, lane.snapshot,
+        request.nomination.closure.records, request.replacements);
+      if (unauthorized.length > 0) {
+        return yield* Effect.fail(memoryFailure(adoptionConflict(request.expectedCanonicalHead, priorHead, unauthorized)));
+      }
+      const changedKeys = new Set(differences.map(({ key }) => key));
+      const changedRecords = request.nomination.closure.records
+        .filter(({ key }) => changedKeys.has(key));
+      if (changedRecords.length === 0) {
+        return adoptionReceipt(adoptionActorId, canonicalAuthorityId,
+          canonicalBinding.bindingSha256, request.nomination.nominationSha256, null,
+          priorHead, priorHead, "already-present");
+      }
+      yield* memoryValue(() => assertAdoptionSnapshotCapacity(lane.snapshot, changedRecords));
+      const changes = canonicalKnowledgeGraphChangesV1(changedRecords
+        .map((record): KnowledgeGraphChangeV1 => ({ kind: "put", record, v: 1 })));
+      const operationId = `memory_adopt_${canonicalSha256({ actorId: adoptionActorId,
+        bindingSha256: canonicalBinding.bindingSha256,
+        nominationSha256: request.nomination.nominationSha256,
+        priorHead, v: 1 }).slice(0, 48)}`;
+      const committed = yield* Effect.exit(canonicalStore.commit({ actorId: adoptionActorId, changes,
+          expectedHead: { generation: priorHead.generation,
+            operationSha256: priorHead.operationSha256 },
+          maximumOperationBytes: maximumCanonicalOperationBytes,
+          operationId }));
+      if (Exit.isFailure(committed)) {
+        const error = Cause.failureOption(committed.cause);
+        if (Option.isNone(error) || error.value._tag !== "MemoryConflict") return yield* Effect.failCause(committed.cause);
+        const actualHead = yield* readPhysicalCanonicalHead();
+        const actualLane = exactHead(actualHead, priorHead)
+          ? yield* readLane(canonicalAuthority, "canonical", actualHead)
+          : yield* proveCanonicalDescendant(canonicalAuthority, priorHead, actualHead);
+        const actualDifferences = adoptionDifferences(actualLane.snapshot,
+          request.nomination.closure.records);
+        if (actualDifferences.length === 0) {
+          if (!exactHead(actualHead, priorHead)) {
+            yield* installCanonicalHead(actualHead);
+          }
+          return adoptionReceipt(adoptionActorId, canonicalAuthorityId,
+            canonicalBinding.bindingSha256, request.nomination.nominationSha256, null,
+            priorHead, actualHead, "already-present");
+        }
+        return yield* Effect.fail(memoryFailure(adoptionConflict(request.expectedCanonicalHead, actualHead, actualDifferences)));
+      }
+      const operation = yield* memoryValue(() => parseOhOperationV1(detachCanonicalData(committed.value,
+        "The returned canonical adoption operation",
+        OH_MEMORY_AUTHORITY_LIMITS_V1.canonicalChangeFeedPageBytes).value));
+      if (operation === null || operation.actorId !== adoptionActorId
+        || operation.operationId !== operationId || operation.spaceId !== canonicalBinding.spaceId
+        || operation.parentOperationSha256 !== priorHead.operationSha256
+        || operation.sequence !== priorHead.sequence + 1
+        || canonicalJson(operation.changes) !== canonicalJson(changes)) {
+        return yield* Effect.fail(memoryFailure(new OhIntegrityError("The canonical authority returned a different adoption operation.")));
+      }
+      const head: OhHeadV1 = immutableClone({ generation: operation.sequence,
+        graphRevisionSha256: operation.graphRevisionSha256,
+        operationSha256: operation.operationSha256, recordsSha256: operation.recordsSha256,
+        sequence: operation.sequence, v: 1 });
+      const actualHead = yield* readPhysicalCanonicalHead();
+      if (!exactHead(actualHead, head)) {
+        const actualLane = exactHead(actualHead, priorHead)
+          ? yield* readLane(canonicalAuthority, "canonical", actualHead)
+          : yield* proveCanonicalDescendant(canonicalAuthority, priorHead, actualHead, head);
+        const actualDifferences = adoptionDifferences(actualLane.snapshot,
+          request.nomination.closure.records);
+        if (actualDifferences.length !== 0) {
+          return yield* Effect.fail(memoryFailure(adoptionConflict(request.expectedCanonicalHead, actualHead, actualDifferences)));
+        }
+        yield* installCanonicalHead(actualHead);
+        return adoptionReceipt(adoptionActorId, canonicalAuthorityId,
+          canonicalBinding.bindingSha256, request.nomination.nominationSha256, null,
+          priorHead, actualHead, "already-present");
+      }
+      yield* installCanonicalHead(actualHead);
+      return adoptionReceipt(adoptionActorId, canonicalAuthorityId,
+        canonicalBinding.bindingSha256, request.nomination.nominationSha256,
+        operation.operationSha256, priorHead, actualHead, "adopted");
+    })));
+
+  return { get agent() { return activeAgent; }, advanceCanonical, adoptNomination };
+});

package/src/memory-authority-runtime.ts

@@ -0,0 +1,40 @@
+import { Cause, Effect, Exit, Option } from "effect";
+import { parseAdoptionRequest, parseCanonicalAdvanceRequest,
+  type OhMemoryAuthorityOptionsV1, type OhMemoryAuthorityV1 } from "./memory-core";
+import { memoryAuthorityLive, type MemoryFailure } from "./memory-authority-platform";
+import { makeMemoryAuthority } from "./memory-authority-program";
+
+function unwrap<A>(exit: Exit.Exit<A, MemoryFailure>): A {
+  if (Exit.isSuccess(exit)) return exit.value;
+  const expected = Cause.failureOption(exit.cause);
+  if (Option.isSome(expected)) throw expected.value.cause;
+  throw Cause.squash(exit.cause);
+}
+
+function run<A>(program: Effect.Effect<A, MemoryFailure, never>): Promise<A> {
+  return Effect.runPromiseExit(program).then(unwrap);
+}
+
+/** Existing Promise surface; stores and agent capability lifetimes remain borrowed. */
+export async function createOhMemoryAuthorityV1(options: OhMemoryAuthorityOptionsV1): Promise<OhMemoryAuthorityV1> {
+  const authority = await run(makeMemoryAuthority.pipe(Effect.provide(memoryAuthorityLive(options))));
+  return Object.freeze({
+    agent: Object.freeze({
+      explain: (value: unknown) => authority.agent.explain(value),
+      nominate: (value: unknown) => authority.agent.nominate(value),
+      query: (value: unknown) => authority.agent.query(value),
+      remember: (value: unknown) => authority.agent.remember(value),
+    }),
+    host: Object.freeze({
+      advanceCanonical: (value: unknown) => {
+        // Detach before enqueueing; caller mutation cannot change a waiting request.
+        try { return run(authority.advanceCanonical(parseCanonicalAdvanceRequest(value))); }
+        catch (cause) { return Promise.reject(cause); }
+      },
+      adoptNomination: (value: unknown) => {
+        try { return run(authority.adoptNomination(parseAdoptionRequest(value))); }
+        catch (cause) { return Promise.reject(cause); }
+      },
+    }),
+  });
+}