@electric-ax/agents-server 0.4.14 → 0.4.16

package/src/entity-manager.ts

@@ -12,6 +12,7 @@ import {
   manifestSourceKey,
   resolveCronScheduleSpec,
 } from '@electric-ax/agents-runtime'
+import type { EventPointer } from '@electric-ax/agents-runtime'
 import {
   ErrCodeDuplicateURL,
   ErrCodeEntityPersistFailed,
@@ -32,6 +33,7 @@ import {
 } from './electric-agents-types.js'
 import { parseDispatchPolicy } from './dispatch-policy-schema.js'
 import { applyTypeDefaultSubscriptionScope } from './routing/dispatch-policy.js'
+import { resolveSandboxForSpawn } from './routing/sandbox.js'
 import {
   isBuiltInSystemPrincipalUrl,
   principalFromCreatedBy,
@@ -71,7 +73,6 @@ import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
 import type { Principal } from './principal.js'
 
 type SpawnPersistResult = [
-  PromiseSettledResult<void>,
   PromiseSettledResult<void>,
   PromiseSettledResult<number>,
 ]
@@ -161,6 +162,16 @@ type ForkSubtreeOptions = {
   rootInstanceId?: string
   waitTimeoutMs?: number
   waitPollMs?: number
+  createdBy?: string
+  /**
+   * Optional anchor pointing at an event on the source root's `main` stream.
+   * When set: only events at or before the pointer are kept on the root's
+   * forked `main`, and the root's manifest is filtered so that descendants
+   * spawned after the pointer are dropped from the fork (their now-orphan
+   * subtrees are not forked). The pointer applies only to the root's
+   * `main` stream; shared-state streams clone at HEAD regardless.
+   */
+  forkPointer?: EventPointer
 }
 
 type ForkEntityPlan = {
@@ -485,7 +496,10 @@ export class EntityManager {
 
   async ensurePrincipal(principal: Principal): Promise<ElectricAgentsEntity> {
     const existing = await this.registry.getEntity(principal.url)
-    if (existing) return existing
+    if (existing) {
+      await this.ensureUserPrincipal(principal)
+      return existing
+    }
     await this.ensurePrincipalEntityType()
     try {
       const entity = await this.spawn(`principal`, {
@@ -510,6 +524,7 @@ export class EntityManager {
           },
         })
       )
+      await this.ensureUserPrincipal(principal)
       return entity
     } catch (error) {
       if (
@@ -517,12 +532,21 @@ export class EntityManager {
         error.code === ErrCodeDuplicateURL
       ) {
         const raced = await this.registry.getEntity(principal.url)
-        if (raced) return raced
+        if (raced) {
+          await this.ensureUserPrincipal(principal)
+          return raced
+        }
       }
       throw error
     }
   }
 
+  private async ensureUserPrincipal(principal: Principal): Promise<void> {
+    if (principal.kind === `user`) {
+      await this.registry.ensureUserForPrincipal(principal)
+    }
+  }
+
   // ==========================================================================
   // Spawn
   // ==========================================================================
@@ -612,7 +636,6 @@ export class EntityManager {
         ? principalUrl(instanceId)
         : `/${typeName}/${instanceId}`
     const mainPath = `${entityURL}/main`
-    const errorPath = `${entityURL}/error`
 
     const subscriptionId = `${typeName}-handler`
 
@@ -650,6 +673,13 @@ export class EntityManager {
           )
         : entityType.default_dispatch_policy
 
+    const sandbox = await resolveSandboxForSpawn(
+      this.registry,
+      dispatchPolicy,
+      req.sandbox,
+      parentEntity
+    )
+
     const now = Date.now()
     const entityData: ElectricAgentsEntity = {
       type: typeName,
@@ -657,13 +687,13 @@ export class EntityManager {
       url: entityURL,
       streams: {
         main: mainPath,
-        error: errorPath,
       },
       subscription_id: subscriptionId,
       dispatch_policy: dispatchPolicy,
       write_token: writeToken,
       tags: initialTags,
       spawn_args: req.args,
+      sandbox,
       type_revision: entityType.revision,
       inbox_schemas: entityType.inbox_schemas,
       state_schemas: entityType.state_schemas,
@@ -725,8 +755,8 @@ export class EntityManager {
     const queueEnterT0 = performance.now()
     const queueWaiting = this.spawnPersistQueue.length()
     const queueRunning = this.spawnPersistQueue.running()
-    const [mainStreamResult, errorStreamResult, entityResult] =
-      await this.spawnPersistQueue.push(async () => {
+    const [mainStreamResult, entityResult] = await this.spawnPersistQueue.push(
+      async () => {
         // Create entity first so it's visible in the DB before stream
         // creation can trigger webhooks that look up the entity.
         let entityTxid: number
@@ -736,41 +766,34 @@ export class EntityManager {
           )
         } catch (err) {
           return [
-            { status: `fulfilled`, value: undefined },
             { status: `fulfilled`, value: undefined },
             { status: `rejected`, reason: err },
           ] as SpawnPersistResult
         }
 
-        const [mainStreamResult, errorStreamResult] = await Promise.allSettled([
+        const [mainStreamResult] = await Promise.allSettled([
           this.streamClient.create(mainPath, {
             contentType,
             body: initialBody,
           }),
-          this.streamClient.create(errorPath, { contentType }),
         ])
 
         return [
           mainStreamResult,
-          errorStreamResult,
           { status: `fulfilled`, value: entityTxid },
         ] as SpawnPersistResult
-      })
+      }
+    )
     const parallelMs = +(performance.now() - queueEnterT0).toFixed(2)
 
     if (
       mainStreamResult.status === `rejected` ||
-      errorStreamResult.status === `rejected` ||
       entityResult.status === `rejected`
     ) {
       const entityReason =
         entityResult.status === `rejected` ? entityResult.reason : null
       const streamReason =
-        mainStreamResult.status === `rejected`
-          ? mainStreamResult.reason
-          : errorStreamResult.status === `rejected`
-            ? errorStreamResult.reason
-            : null
+        mainStreamResult.status === `rejected` ? mainStreamResult.reason : null
       const isDuplicate = entityReason instanceof EntityAlreadyExistsError
       const isStreamConflict =
         !!streamReason &&
@@ -785,9 +808,6 @@ export class EntityManager {
         if (mainStreamResult.status === `fulfilled`) {
           rollbacks.push(this.streamClient.delete(mainPath))
         }
-        if (errorStreamResult.status === `fulfilled`) {
-          rollbacks.push(this.streamClient.delete(errorPath))
-        }
         if (entityResult.status === `fulfilled`) {
           rollbacks.push(this.registry.deleteEntity(entityURL))
         }
@@ -814,9 +834,7 @@ export class EntityManager {
       const failure =
         mainStreamResult.status === `rejected`
           ? mainStreamResult.reason
-          : errorStreamResult.status === `rejected`
-            ? errorStreamResult.reason
-            : (entityResult as PromiseRejectedResult).reason
+          : (entityResult as PromiseRejectedResult).reason
       if (failure instanceof Error) throw failure
       throw new ElectricAgentsError(
         `SPAWN_FAILED`,
@@ -873,7 +891,36 @@ export class EntityManager {
     const writeStreamLocks = new Set<string>()
 
     try {
-      const sourceTree = await this.waitForIdleSubtree(rootUrl, opts, workLocks)
+      // For pointer-forks we read the source root HISTORICALLY at a
+      // frozen offset, so concurrent activity on the root past the
+      // pointer can't tear our snapshot — we don't need to wait for
+      // the root to be idle (which would block the "click fork right
+      // after the response landed" case, since the runtime keeps the
+      // worker warm for `idleTimeout`). We still wait+lock any kept
+      // descendants below (after `computeEffectiveSubtree` runs), since
+      // those are HEAD-cloned and need a stable snapshot. For HEAD-forks
+      // the old all-idle requirement still applies.
+      let sourceTree: Array<ElectricAgentsEntity>
+      if (opts.forkPointer) {
+        const rootEntity = await this.registry.getEntity(rootUrl)
+        if (!rootEntity) {
+          throw new ElectricAgentsError(
+            ErrCodeNotFound,
+            `Entity not found`,
+            404
+          )
+        }
+        if (isTerminalEntityStatus(rootEntity.status)) {
+          throw new ElectricAgentsError(
+            ErrCodeNotRunning,
+            `Cannot fork terminal entity "${rootEntity.url}"`,
+            409
+          )
+        }
+        sourceTree = await this.listEntitySubtree(rootEntity)
+      } else {
+        sourceTree = await this.waitForIdleSubtree(rootUrl, opts, workLocks)
+      }
       const sourceRoot = sourceTree[0]!
       if (sourceRoot.parent) {
         throw new ElectricAgentsError(
@@ -883,9 +930,107 @@ export class EntityManager {
         )
       }
 
-      const snapshot = await this.readForkStateSnapshot(sourceTree)
+      // When forking at a pointer, pre-read the root's main, validate the
+      // pointer against the source's true history, and materialise the
+      // root-at-pointer snapshot fragments. The pointer only applies to
+      // the root's `main` stream. Descendants kept by the manifest filter
+      // are forked at HEAD.
+      //
+      // Pointer→position translation: the runtime mints pointers as
+      // `{ offset: previousBatchOffset, subOffset: itemIndex+1 }`, where
+      // the anchor offset is the END of the delivery batch that
+      // PRECEDED the targeted event. The durable-streams server
+      // interprets `{ X, N }` as "from offset X, take N flattened
+      // messages forward" — independent of how delivery is chunked. We
+      // mirror that interpretation here by translating the pointer to a
+      // 1-indexed CUMULATIVE position in the source's flattened
+      // history, then filtering events with position ≤ that target.
+      let preFilteredRoot:
+        | {
+            manifests: Map<string, Record<string, unknown>>
+            childStatuses: Map<string, Record<string, unknown>>
+            replayWatermarks: Map<string, Record<string, unknown>>
+            sharedStateIds: Set<string>
+          }
+        | undefined
+      if (opts.forkPointer) {
+        const sourceEvents = await this.streamClient.readJson<
+          Record<string, unknown>
+        >(sourceRoot.streams.main)
+        const flat = sourceEvents.flatMap((item) =>
+          Array.isArray(item) ? item : [item]
+        ) as Array<Record<string, unknown>>
+        const target = this.resolveForkPointerTarget(
+          flat,
+          opts.forkPointer,
+          sourceRoot.streams.main
+        )
+        const filteredEvents = flat.slice(0, target)
+        const rootManifests = this.reduceStateRows(filteredEvents, `manifest`)
+        const sharedStateIds = new Set<string>()
+        for (const manifest of rootManifests.values()) {
+          this.collectSharedStateIds(manifest, sharedStateIds)
+        }
+        preFilteredRoot = {
+          manifests: rootManifests,
+          childStatuses: this.reduceStateRows(filteredEvents, `child_status`),
+          replayWatermarks: this.reduceStateRows(
+            filteredEvents,
+            `replay_watermark`
+          ),
+          sharedStateIds,
+        }
+      }
+
+      const effectiveSubtree = preFilteredRoot
+        ? this.computeEffectiveSubtree(
+            sourceTree,
+            sourceRoot.url,
+            preFilteredRoot.manifests
+          )
+        : sourceTree
+
+      // For pointer-forks, kept descendants (everything in the effective
+      // subtree except the root) are HEAD-cloned, so they must be idle
+      // before we read their snapshots. Wait+lock only those — the root
+      // was skipped above.
+      if (opts.forkPointer) {
+        const descendants = effectiveSubtree.filter(
+          (entity) => entity.url !== sourceRoot.url
+        )
+        if (descendants.length > 0) {
+          await this.waitForGivenEntitiesIdle(descendants, opts, workLocks)
+        }
+      }
+
+      const snapshot = await this.readForkStateSnapshot(
+        // Skip the root when we've already pre-filtered it — avoid both a
+        // wasted HEAD read of main and a re-population that would clobber
+        // the filtered entries.
+        preFilteredRoot
+          ? effectiveSubtree.filter((entity) => entity.url !== sourceRoot.url)
+          : effectiveSubtree
+      )
+      if (preFilteredRoot) {
+        snapshot.manifestsByEntity.set(
+          sourceRoot.url,
+          preFilteredRoot.manifests
+        )
+        snapshot.childStatusesByEntity.set(
+          sourceRoot.url,
+          preFilteredRoot.childStatuses
+        )
+        snapshot.replayWatermarksByEntity.set(
+          sourceRoot.url,
+          preFilteredRoot.replayWatermarks
+        )
+        for (const id of preFilteredRoot.sharedStateIds) {
+          snapshot.sharedStateIds.add(id)
+        }
+      }
+
       const suffix = randomUUID().slice(0, 8)
-      const entityUrlMap = await this.buildForkEntityUrlMap(sourceTree, {
+      const entityUrlMap = await this.buildForkEntityUrlMap(effectiveSubtree, {
         suffix,
         rootUrl,
         rootInstanceId: opts.rootInstanceId,
@@ -896,14 +1041,15 @@ export class EntityManager {
       )
       const stringMap = this.buildForkStringMap(entityUrlMap, sharedStateIdMap)
       const entityPlans = this.buildForkEntityPlans(
-        sourceTree,
+        effectiveSubtree,
         entityUrlMap,
-        stringMap
+        stringMap,
+        opts.createdBy
       )
 
       this.addForkLocks(
         this.forkWriteLockedEntities,
-        sourceTree.map((entity) => entity.url),
+        effectiveSubtree.map((entity) => entity.url),
         writeEntityLocks
       )
       this.addForkLocks(
@@ -921,16 +1067,15 @@ export class EntityManager {
 
       try {
         for (const plan of entityPlans) {
+          const isRoot = plan.source.url === rootUrl
           await this.streamClient.fork(
             plan.fork.streams.main,
-            plan.source.streams.main
+            plan.source.streams.main,
+            isRoot && opts.forkPointer
+              ? { forkPointer: opts.forkPointer }
+              : undefined
           )
           createdStreams.push(plan.fork.streams.main)
-          await this.streamClient.fork(
-            plan.fork.streams.error,
-            plan.source.streams.error
-          )
-          createdStreams.push(plan.fork.streams.error)
         }
 
         for (const [sourceId, forkId] of sharedStateIdMap) {
@@ -1081,6 +1226,73 @@ export class EntityManager {
     held.clear()
   }
 
+  /**
+   * Variant of {@link waitForIdleSubtree} that takes an explicit entity
+   * list instead of walking the registry from `rootUrl`. Used by the
+   * pointer-fork path to wait+lock only the kept descendants, since
+   * the root is being forked from history and doesn't need to be idle.
+   */
+  private async waitForGivenEntitiesIdle(
+    entities: ReadonlyArray<ElectricAgentsEntity>,
+    opts: ForkSubtreeOptions,
+    workLocks: Set<string>
+  ): Promise<void> {
+    if (entities.length === 0) return
+
+    const timeoutMs = opts.waitTimeoutMs ?? DEFAULT_FORK_WAIT_TIMEOUT_MS
+    const pollMs = opts.waitPollMs ?? DEFAULT_FORK_WAIT_POLL_MS
+
+    const refresh = async (): Promise<Array<ElectricAgentsEntity>> => {
+      const refreshed = await Promise.all(
+        entities.map((entity) => this.registry.getEntity(entity.url))
+      )
+      return refreshed.filter(
+        (entity): entity is ElectricAgentsEntity => !!entity
+      )
+    }
+
+    const deadline = Date.now() + timeoutMs
+    while (true) {
+      const present = await refresh()
+      const stopped = present.find((entity) =>
+        isTerminalEntityStatus(entity.status)
+      )
+      if (stopped) {
+        throw new ElectricAgentsError(
+          ErrCodeNotRunning,
+          `Cannot fork terminal entity "${stopped.url}"`,
+          409
+        )
+      }
+      let active = present.filter(
+        (entity) => entity.status !== `idle` && entity.status !== `paused`
+      )
+      if (active.length === 0) {
+        this.addForkLocks(
+          this.forkWorkLockedEntities,
+          present.map((entity) => entity.url),
+          workLocks
+        )
+        const reChecked = await refresh()
+        const reActive = reChecked.filter(
+          (entity) => entity.status !== `idle` && entity.status !== `paused`
+        )
+        if (reActive.length === 0) return
+        this.releaseForkLocks(this.forkWorkLockedEntities, workLocks)
+        active = reActive
+      }
+      if (Date.now() >= deadline) {
+        throw new ElectricAgentsError(
+          ErrCodeForkWaitTimeout,
+          `Timed out waiting for descendants to become idle`,
+          409,
+          { active: active.map((entity) => entity.url) }
+        )
+      }
+      await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())))
+    }
+  }
+
   private async waitForIdleSubtree(
     rootUrl: string,
     opts: ForkSubtreeOptions,
@@ -1175,6 +1387,116 @@ export class EntityManager {
     }
   }
 
+  /**
+   * Translate `forkPointer` into a 1-indexed CUMULATIVE position in the
+   * source's flattened history. Throws a 400 if the pointer doesn't
+   * address a real event.
+   *
+   * Semantics (mirroring the durable-streams server interpretation):
+   * `{ offset: X, subOffset: N }` means "from anchor X, take N flattened
+   * messages forward." Concretely, the target event is the N-th event
+   * after the last event whose `headers.offset` is ≤ X. (When `X` is
+   * `null`, the anchor is the stream start and the target is the N-th
+   * event from the very beginning.) The returned position is the count
+   * of events to KEEP — events 1..position survive the filter.
+   *
+   * A pointer is valid when:
+   *   - `pointer.offset` is `null` (stream start) OR matches some
+   *     event's `headers.offset` value, AND
+   *   - `pointer.subOffset` is in `[1, total events past the anchor]`.
+   */
+  private resolveForkPointerTarget(
+    events: ReadonlyArray<Record<string, unknown>>,
+    pointer: EventPointer,
+    streamPath: string
+  ): number {
+    // Count events at-or-before the anchor and validate the anchor exists.
+    // `pointer.offset === null` is the stream-start anchor — no events
+    // precede it, so `positionAtAnchor` stays at 0.
+    let positionAtAnchor = 0
+    let anchorSeen = pointer.offset === null
+    for (const event of events) {
+      const headers = isRecord(event.headers) ? event.headers : undefined
+      const eventOffset =
+        typeof headers?.offset === `string` ? headers.offset : undefined
+      if (eventOffset === undefined) continue
+      if (pointer.offset === null) continue
+      if (eventOffset === pointer.offset) anchorSeen = true
+      if (eventOffset <= pointer.offset) positionAtAnchor++
+    }
+    if (!anchorSeen) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `fork_pointer.offset (${pointer.offset ?? `<stream-start>`}) does not match any event's Stream-Next-Offset on ${streamPath}`,
+        400
+      )
+    }
+    const eventsPastAnchor = events.length - positionAtAnchor
+    if (pointer.subOffset < 1 || pointer.subOffset > eventsPastAnchor) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `fork_pointer.sub_offset ${pointer.subOffset} out of range past anchor on ${streamPath} (valid: 1..${eventsPastAnchor})`,
+        400
+      )
+    }
+    return positionAtAnchor + pointer.subOffset
+  }
+
+  /**
+   * Compute the subset of `sourceTree` that survives the manifest filter
+   * applied at the root. After filtering the root's manifest at the fork
+   * pointer, only children whose manifest entries landed at or before the
+   * pointer remain; those kept children carry their CURRENT (HEAD) subtree
+   * along with them. Children dropped from the root's manifest, and any
+   * of their descendants, are excluded.
+   */
+  private computeEffectiveSubtree(
+    sourceTree: ReadonlyArray<ElectricAgentsEntity>,
+    rootUrl: string,
+    filteredRootManifests: ReadonlyMap<string, Record<string, unknown>>
+  ): Array<ElectricAgentsEntity> {
+    const keptChildUrls = new Set<string>()
+    for (const value of filteredRootManifests.values()) {
+      if (value.kind === `child` && typeof value.entity_url === `string`) {
+        keptChildUrls.add(value.entity_url)
+      }
+    }
+
+    const childrenByParent = new Map<string, Array<ElectricAgentsEntity>>()
+    for (const entity of sourceTree) {
+      if (!entity.parent) continue
+      const list = childrenByParent.get(entity.parent) ?? []
+      list.push(entity)
+      childrenByParent.set(entity.parent, list)
+    }
+
+    const rootEntity = sourceTree.find((e) => e.url === rootUrl)
+    if (!rootEntity) return []
+
+    const result: Array<ElectricAgentsEntity> = [rootEntity]
+    const queue: Array<ElectricAgentsEntity> = []
+    for (const child of childrenByParent.get(rootUrl) ?? []) {
+      if (keptChildUrls.has(child.url)) {
+        queue.push(child)
+      }
+    }
+    const seen = new Set<string>([rootUrl])
+    while (queue.length > 0) {
+      const entity = queue.shift()!
+      if (seen.has(entity.url)) continue
+      seen.add(entity.url)
+      result.push(entity)
+      // Below the kept-children level the existing recursive subtree is
+      // included unchanged — kept descendants are HEAD-cloned.
+      for (const grandchild of childrenByParent.get(entity.url) ?? []) {
+        if (!seen.has(grandchild.url)) {
+          queue.push(grandchild)
+        }
+      }
+    }
+    return result
+  }
+
   private async listEntitySubtree(
     root: ElectricAgentsEntity
   ): Promise<Array<ElectricAgentsEntity>> {
@@ -1381,7 +1703,6 @@ export class EntityManager {
     for (const [sourceUrl, forkUrl] of entityUrlMap) {
       stringMap.set(sourceUrl, forkUrl)
       stringMap.set(`${sourceUrl}/main`, `${forkUrl}/main`)
-      stringMap.set(`${sourceUrl}/error`, `${forkUrl}/error`)
     }
     for (const [sourceId, forkId] of sharedStateIdMap) {
       stringMap.set(sourceId, forkId)
@@ -1396,7 +1717,8 @@ export class EntityManager {
   private buildForkEntityPlans(
     entitiesToFork: Array<ElectricAgentsEntity>,
     entityUrlMap: Map<string, string>,
-    stringMap: Map<string, string>
+    stringMap: Map<string, string>,
+    createdBy?: string
   ): Array<ForkEntityPlan> {
     const now = Date.now()
     return entitiesToFork.map((source) => {
@@ -1420,12 +1742,12 @@ export class EntityManager {
         status: `idle`,
         streams: {
           main: `${forkUrl}/main`,
-          error: `${forkUrl}/error`,
         },
         subscription_id: `${type}-handler`,
         write_token: randomUUID(),
         spawn_args: spawnArgs,
         parent,
+        created_by: createdBy ?? source.created_by,
         created_at: now,
         updated_at: now,
       }
@@ -1717,12 +2039,7 @@ export class EntityManager {
     manifests: Map<string, Record<string, unknown>>
   ): Promise<void> {
     for (const [manifestKey, manifest] of manifests) {
-      await this.syncEntitiesManifestSource(
-        entityUrl,
-        manifestKey,
-        `upsert`,
-        manifest
-      )
+      await this.syncManifestLinks(entityUrl, manifestKey, `upsert`, manifest)
 
       const wake = buildManifestWakeRegistration(
         entityUrl,
@@ -1795,6 +2112,7 @@ export class EntityManager {
       {
         entityUrl: targetUrl,
         from: senderUrl,
+        from_agent: senderUrl,
         payload: manifest.payload,
         key: `scheduled-${producerId}`,
         type:
@@ -1861,7 +2179,7 @@ export class EntityManager {
       `msg-in-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
 
     const value: Record<string, unknown> = {
-      from: req.from,
+      from: req.from_principal ?? req.from,
       payload: req.payload,
       timestamp: now,
       mode: req.mode ?? `immediate`,
@@ -1870,6 +2188,12 @@ export class EntityManager {
           ? `pending`
           : `processed`,
     }
+    if (req.from_principal) {
+      value.from_principal = req.from_principal
+    }
+    if (req.from_agent) {
+      value.from_agent = req.from_agent
+    }
     if (req.type) {
       value.message_type = req.type
     }
@@ -2280,14 +2604,21 @@ export class EntityManager {
     return updated
   }
 
-  async ensureEntitiesMembershipStream(tags: Record<string, string>): Promise<{
+  async ensureEntitiesMembershipStream(
+    tags: Record<string, string>,
+    principal: { url: string; kind: string }
+  ): Promise<{
     sourceRef: string
     streamUrl: string
   }> {
     if (!this.entityBridgeManager) {
       throw new Error(`Entity bridge manager not configured`)
     }
-    return this.entityBridgeManager.register(this.validateTags(tags))
+    return this.entityBridgeManager.register(
+      this.validateTags(tags),
+      principal.url,
+      principal.kind
+    )
   }
 
   async writeManifestEntry(
@@ -2320,12 +2651,12 @@ export class EntityManager {
       await this.streamClient.appendIdempotent(entity.streams.main, encoded, {
         producerId: opts.producerId,
       })
-      await this.syncEntitiesManifestSource(entityUrl, key, operation, value)
+      await this.syncManifestLinks(entityUrl, key, operation, value)
       return
     }
 
     await this.streamClient.append(entity.streams.main, encoded)
-    await this.syncEntitiesManifestSource(entityUrl, key, operation, value)
+    await this.syncManifestLinks(entityUrl, key, operation, value)
   }
 
   async upsertCronSchedule(
@@ -2620,6 +2951,8 @@ export class EntityManager {
       {
         entityUrl,
         from: req.from,
+        from_principal: req.from_principal,
+        from_agent: req.from_agent,
         payload: req.payload,
         key: req.key,
         type: req.type,
@@ -2701,7 +3034,7 @@ export class EntityManager {
     })
   }
 
-  private async syncEntitiesManifestSource(
+  private async syncManifestLinks(
     entityUrl: string,
     manifestKey: string,
     operation: `insert` | `update` | `upsert` | `delete`,
@@ -2714,6 +3047,14 @@ export class EntityManager {
       manifestKey,
       sourceRef
     )
+
+    const sharedStateId =
+      operation === `delete` ? undefined : this.extractSharedStateId(value)
+    await this.registry.replaceSharedStateLink(
+      entityUrl,
+      manifestKey,
+      sharedStateId
+    )
   }
 
   private extractEntitiesSourceRef(
@@ -2729,6 +3070,24 @@ export class EntityManager {
     return undefined
   }
 
+  private extractSharedStateId(
+    manifest?: Record<string, unknown>
+  ): string | undefined {
+    if (manifest?.kind === `shared-state` && typeof manifest.id === `string`) {
+      return manifest.id
+    }
+
+    if (manifest?.kind !== `source` || manifest.sourceType !== `db`) {
+      return undefined
+    }
+
+    if (typeof manifest.sourceRef === `string`) {
+      return manifest.sourceRef
+    }
+    const config = isRecord(manifest.config) ? manifest.config : undefined
+    return typeof config?.id === `string` ? config.id : undefined
+  }
+
   /**
    * Read a child entity's stream and extract concatenated text deltas
    * for a specific run, plus any error messages for that run.
@@ -3004,19 +3363,8 @@ export class EntityManager {
       return
     }
 
-    const errorCloseEvent = {
-      type: `signal`,
-      key: signalEvent.key,
-      value: signalEvent.value,
-      headers: signalEvent.headers,
-    }
-    const errorSignalData = this.encodeChangeEvent(
-      errorCloseEvent as unknown as Record<string, unknown>
-    )
-
     for (const [streamPath, data] of [
       [entity.streams.main, signalData],
-      [entity.streams.error, errorSignalData],
     ] as const) {
       try {
         await this.streamClient.append(streamPath, data, { close: true })
@@ -3201,6 +3549,7 @@ export class EntityManager {
         streams: entity.streams,
         tags: entity.tags,
         spawnArgs: entity.spawn_args,
+        sandbox: entity.sandbox,
         createdBy: entity.created_by,
       },
       principal: principalFromCreatedBy(entity.created_by),