@animalabs/context-manager 0.4.0 → 0.5.1

package/src/context-manager.ts

@@ -211,6 +211,11 @@ export class ContextManager {
 
   /**
    * Add a message to the store.
+   *
+   * If the configured strategy implements `chunkIngressMessage` and returns
+   * a non-null sharding decision, the message is stored as multiple records
+   * sharing a `bodyGroupId` (per the adaptive-resolution design §3.6). The
+   * returned MessageId is the first shard's id.
    */
   addMessage(
     participant: string,
@@ -218,6 +223,33 @@ export class ContextManager {
     metadata?: MessageMetadata,
     causedBy?: MessageId[]
   ): MessageId {
+    // Optional strategy-driven ingestion-time chunking
+    const strategyAny = this.strategy as unknown as {
+      chunkIngressMessage?: (
+        participant: string,
+        content: ContentBlock[]
+      ) => { bodyGroupId: string; shards: Array<{ content: ContentBlock[]; shardIndex: number }> } | null;
+    };
+    if (typeof strategyAny.chunkIngressMessage === 'function') {
+      const decision = strategyAny.chunkIngressMessage(participant, content);
+      if (decision && decision.shards.length > 1) {
+        let firstId: MessageId | null = null;
+        for (const shard of decision.shards) {
+          const message = this.messageStore.append(
+            participant,
+            shard.content,
+            metadata,
+            causedBy,
+            {
+              bodyGroupId: decision.bodyGroupId,
+              shardIndex: shard.shardIndex,
+            }
+          );
+          if (firstId === null) firstId = message.id;
+        }
+        return firstId!;
+      }
+    }
     const message = this.messageStore.append(participant, content, metadata, causedBy);
     return message.id;
   }

package/src/index.ts

@@ -10,7 +10,7 @@ export { BlobManager } from './blob-manager.js';
 
 // Strategies
 export { PassthroughStrategy } from './strategies/passthrough.js';
-export { AutobiographicalStrategy } from './strategies/autobiographical.js';
+export { AutobiographicalStrategy, type AutobiographicalProgressSnapshot } from './strategies/autobiographical.js';
 export { KnowledgeStrategy } from './strategies/knowledge.js';
 
 // Types

package/src/message-store.ts

@@ -101,14 +101,31 @@ export class MessageStore {
     }
   }
 
+  /**
+   * Optional extra fields for `append`, used by callers that need to set
+   * adaptive-resolution metadata (bodyGroupId for shards, initial
+   * resolution state, etc.) at ingestion time.
+   */
+  static readonly _appendExtraKeys = ['bodyGroupId', 'shardIndex', 'currentResolution', 'lockedByAgent'] as const;
+
   /**
    * Append a new message to the store.
+   *
+   * `extra` is an optional bag of adaptive-resolution metadata
+   * (bodyGroupId / shardIndex / currentResolution / lockedByAgent) that
+   * callers may set at ingestion. Field semantics match StoredMessage.
    */
   append(
     participant: string,
     content: ContentBlock[],
     metadata?: MessageMetadata,
-    causedBy?: MessageId[]
+    causedBy?: MessageId[],
+    extra?: {
+      bodyGroupId?: string;
+      shardIndex?: number;
+      currentResolution?: number;
+      lockedByAgent?: boolean;
+    }
   ): StoredMessage {
     // Extract blobs from content
     const storedContent = this.blobManager.extractBlobs(content);
@@ -120,28 +137,54 @@ export class MessageStore {
       metadata,
       timestamp: Date.now(),
       causedBy,
+      ...(extra ?? {}),
     };
 
     const record = this.store.appendToStateJson(this.stateId, partialInternal);
     const index = this.length() - 1;
 
-    // Now update the stored item to include the id (for rebuildIndex)
+    // The append's payload doesn't carry the chronicle record's id /
+    // sequence — those are only known once the append returns. We patch
+    // them in via editStateItem below. The patch creates a new chronicle
+    // record at `record.sequence + 1` (the next sequence; nothing else
+    // writes between the append and the edit inside this function).
+    //
+    // We store the EDIT'S sequence (not the original append's) as the
+    // canonical "this message is fully readable at and after this seq"
+    // marker. Why: `ContextManager.branchAt(messageId)` forwards
+    // `message.sequence` to `chronicle.createBranchAt`, which forks
+    // visibility at that exact seq. If `sequence` pointed at the original
+    // append (record.sequence), the new branch would see the pre-patch
+    // payload (id/sequence undefined). Pointing at the edit's seq
+    // includes the patched payload in the inherited records — so a
+    // forked branch sees this message in its fully-established form.
+    //
+    // Invariant: this function does exactly ONE chronicle write between
+    // the append and the edit (the edit itself). If that ever changes,
+    // the +1 expression must be updated to match (or refactored to
+    // capture editStateItem's returned record.sequence — which is
+    // chicken-and-egg here since we need the value inside the payload
+    // we're writing).
+    const commitSequence = record.sequence + 1;
     const fullInternal: StoredMessageInternal = {
       id: record.id,
-      sequence: record.sequence,
+      sequence: commitSequence,
       ...partialInternal,
     };
     this.store.editStateItem(this.stateId, index, Buffer.from(JSON.stringify(fullInternal)));
 
-    // Build full message with ID and sequence from record
+    // Build full message with ID and sequence from record. The sequence
+    // we expose is the commit sequence (matches what's stored), so
+    // `branchAt(messageId)` forks at the right place for any caller.
     const message: StoredMessage = {
       id: record.id,
-      sequence: record.sequence,
+      sequence: commitSequence,
       participant,
       content, // Original content with inline data
       metadata,
       timestamp: new Date(partialInternal.timestamp),
       causedBy,
+      ...(extra ?? {}),
     };
 
     // Update index
@@ -153,6 +196,11 @@ export class MessageStore {
 
   /**
    * Edit a message's content.
+   *
+   * Throws if `messageId` belongs to a bodyGroup (i.e., is a shard of a
+   * larger sharded message). Editing one shard would silently corrupt the
+   * bodyGroup's byte-faithful reassembly invariant. To replace a sharded
+   * message, remove the whole bodyGroup and re-append.
    */
   edit(messageId: MessageId, newContent: ContentBlock[]): void {
     const index = this.idToIndex.get(messageId);
@@ -165,6 +213,13 @@ export class MessageStore {
       throw new Error(`Message not found at index: ${index}`);
     }
 
+    if (oldMessage.bodyGroupId) {
+      throw new Error(
+        `Cannot edit shard ${messageId}: it is part of bodyGroup ${oldMessage.bodyGroupId}. ` +
+          `Sharded messages are immutable — remove the whole bodyGroup and re-append instead.`,
+      );
+    }
+
     const oldContent = this.blobManager.resolveBlobs(oldMessage.content);
     const storedContent = this.blobManager.extractBlobs(newContent);
 
@@ -181,6 +236,11 @@ export class MessageStore {
 
   /**
    * Remove a message from the store.
+   *
+   * For a sharded message (one shard of a bodyGroup), the caller MUST
+   * remove all shards in the group together — removing one shard would
+   * orphan the rest and break byte-faithful reassembly. Use
+   * `removeBodyGroup(id)` for that case.
    */
   remove(messageId: MessageId): void {
     const index = this.idToIndex.get(messageId);
@@ -188,14 +248,61 @@ export class MessageStore {
       throw new Error(`Message not found: ${messageId}`);
     }
 
+    const target = this.getInternal(index);
+    if (target?.bodyGroupId) {
+      throw new Error(
+        `Cannot remove shard ${messageId} in isolation: it is part of bodyGroup ${target.bodyGroupId}. ` +
+          `Use removeBodyGroup(${messageId}) to remove all shards atomically.`,
+      );
+    }
+
     this.store.redactStateItems(this.stateId, index, index + 1);
     this.rebuildIndex();
 
     this.emit({ type: 'remove', messageId });
   }
 
+  /**
+   * Remove every shard of the bodyGroup containing `messageId`. If the
+   * message is not part of a bodyGroup, falls back to single-message
+   * remove. Atomic from the caller's perspective.
+   */
+  removeBodyGroup(messageId: MessageId): void {
+    const index = this.idToIndex.get(messageId);
+    if (index === undefined) {
+      throw new Error(`Message not found: ${messageId}`);
+    }
+    const target = this.getInternal(index);
+    if (!target?.bodyGroupId) {
+      // Not sharded — defer to normal remove path (re-look up via getInternal
+      // since the normal `remove` checks bodyGroupId).
+      this.store.redactStateItems(this.stateId, index, index + 1);
+      this.rebuildIndex();
+      this.emit({ type: 'remove', messageId });
+      return;
+    }
+    // Find the contiguous run of shards with this bodyGroupId. Shards are
+    // stored consecutively (they're appended one after the other at
+    // ingestion), so we can scan outward from `index`.
+    const groupId = target.bodyGroupId;
+    const all = this.getAllInternal();
+    let from = index;
+    while (from > 0 && all[from - 1].bodyGroupId === groupId) from--;
+    let to = index;
+    while (to + 1 < all.length && all[to + 1].bodyGroupId === groupId) to++;
+    const firstId = all[from].id;
+    const lastId = all[to].id;
+    this.store.redactStateItems(this.stateId, from, to + 1);
+    this.rebuildIndex();
+    this.emit({ type: 'removeRange', fromId: firstId, toId: lastId });
+  }
+
   /**
    * Remove a range of messages from the store.
+   *
+   * If the range starts or ends in the middle of a bodyGroup, throws —
+   * removeRange must align to bodyGroup boundaries. (Use `removeBodyGroup`
+   * to remove an entire group, then call `removeRange` over plain messages.)
    */
   removeRange(fromId: MessageId, toId: MessageId): void {
     const fromIndex = this.idToIndex.get(fromId);
@@ -208,6 +315,21 @@ export class MessageStore {
       throw new Error(`Message not found: ${toId}`);
     }
 
+    // Verify the range doesn't bisect a bodyGroup.
+    const all = this.getAllInternal();
+    const startGroup = all[fromIndex].bodyGroupId;
+    const endGroup = all[toIndex].bodyGroupId;
+    if (startGroup && fromIndex > 0 && all[fromIndex - 1].bodyGroupId === startGroup) {
+      throw new Error(
+        `removeRange would bisect bodyGroup ${startGroup} at start. Use removeBodyGroup(${fromId}) first.`,
+      );
+    }
+    if (endGroup && toIndex + 1 < all.length && all[toIndex + 1].bodyGroupId === endGroup) {
+      throw new Error(
+        `removeRange would bisect bodyGroup ${endGroup} at end. Use removeBodyGroup(${toId}) first.`,
+      );
+    }
+
     this.store.redactStateItems(this.stateId, fromIndex, toIndex + 1);
     this.rebuildIndex();
 
@@ -457,17 +579,34 @@ export class MessageStore {
   private internalToStored(
     internal: StoredMessageInternal,
     id: MessageId,
-    index: number
+    _index: number,
   ): StoredMessage {
-    return {
+    const stored: StoredMessage = {
       id,
-      sequence: index, // Use index as sequence for now
+      // chronicle record sequence captured when the message was appended
+      // (see `add()` line 131: `sequence: record.sequence`). The previous
+      // implementation returned the slot index ("// Use index as sequence
+      // for now"), which silently corrupted any downstream code that
+      // forwarded this number to chronicle APIs expecting a real sequence
+      // — most notably `ContextManager.branchAt`, which would fork the
+      // chronicle at the index-mistaken-for-sequence and lose every
+      // record between the intended fork point and the actual one. For
+      // typical autobio sessions the index-vs-sequence ratio is ~1:2
+      // (each message append is accompanied by ~1 autobio state update),
+      // so /undo of a 800-message conversation forked ~400 messages back.
+      sequence: internal.sequence,
       participant: internal.participant,
       content: this.blobManager.resolveBlobs(internal.content),
       metadata: internal.metadata,
       timestamp: new Date(internal.timestamp),
       causedBy: internal.causedBy,
     };
+    // Carry adaptive-resolution fields through unchanged.
+    if (internal.bodyGroupId !== undefined) stored.bodyGroupId = internal.bodyGroupId;
+    if (internal.shardIndex !== undefined) stored.shardIndex = internal.shardIndex;
+    if (internal.currentResolution !== undefined) stored.currentResolution = internal.currentResolution;
+    if (internal.lockedByAgent !== undefined) stored.lockedByAgent = internal.lockedByAgent;
+    return stored;
   }
 }