@rikalabs/akter 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.2 (2026-10-15)
+
+The framework and CLI release together at `0.2.2` on the `latest` npm dist-tag. Stores written by 0.2.0 and 0.2.1 open unchanged.
+
+- A fork of a position older than every retained checkpoint is refused with `ForkRefused("retention")` once retention has trimmed its log prefix. It was reported as `CorruptSegment`, as if the store had lost data. A segment missing inside retention is still `CorruptSegment`.
+- The retention refusal is decided from the newest position the oldest retained checkpoint covers (including a fork installed into its shard), so losing in-window segments through that checkpoint is still `CorruptSegment`.
+- New public field: `HistoryCheckpoint` (exported from `@rikalabs/akter/server`) gains a required `expired` boolean. `Store.history.checkpoints` sets it when the checkpoint's offset precedes the oldest stored segment written within retention. It is informational; forks do not use it.
+
 ## 0.2.1 (2026-10-14)
 
 The framework and CLI release together at `0.2.1` on the `latest` npm dist-tag. Stores written by 0.2.0 open unchanged, and a publication epoch 0.2.0 left stranded expires on its own once a 0.2.1 runner or collector reaches it. Do not run `Store.collect` against a store while a 0.2.0 runner of it is still live.

package/dist/serve/handlers.d.ts

@@ -16,7 +16,12 @@ export declare const STREAM_BUFFER = 64;
 declare const make: (engine: Engine, actors: ReadonlyArray<AnyActor>, sessions: Sessions, routing?: Sharding["Service"]) => {
     [k: string]: Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
         readonly id: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-    }>, import("effect/rpc/RpcSchema").Stream<Schema.Codec<Schema.Json, Schema.Json, never, never>, Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
+        readonly commandId: Schema.String;
+        readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>, Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly replayed: Schema.Boolean;
+    }>, Schema.Union<readonly [Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
         readonly reason: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unauthorized", {
             readonly code: Schema.Literals<readonly ["missing_credentials", "invalid_credentials", "expired", "access_denied", "outcome_access_denied", "reauthorization_unavailable"]>;
         }>, Schema.TaggedStruct<"InvalidInput", {
@@ -46,31 +51,12 @@ declare const make: (engine: Engine, actors: ReadonlyArray<AnyActor>, sessions:
         }>]>;
         readonly isRetryable: Schema.Boolean;
         readonly retryAfter: Schema.optionalKey<Schema.Finite>;
-    }>, never, never>>, Schema.Never, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
+    }>, never, never>, Schema.TaggedStruct<"ActionFailed", {
+        readonly error: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly replayed: Schema.Boolean;
+    }>]>, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
         readonly id: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-    }>, import("effect/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
-        readonly kind: Schema.Literal<"Frame">;
-        readonly version: Schema.Finite;
-        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"Patch">;
-        readonly version: Schema.Finite;
-        readonly ops: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
-            readonly op: Schema.Literal<"add">;
-            readonly path: Schema.String;
-            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-            readonly description: Schema.optionalKey<Schema.String>;
-        }>, Schema.Struct<{
-            readonly op: Schema.Literal<"remove">;
-            readonly path: Schema.String;
-            readonly description: Schema.optionalKey<Schema.String>;
-        }>, Schema.Struct<{
-            readonly op: Schema.Literal<"replace">;
-            readonly path: Schema.String;
-            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-            readonly description: Schema.optionalKey<Schema.String>;
-        }>]>>;
-    }>]>, Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
+    }>, import("effect/rpc/RpcSchema").Stream<Schema.Codec<Schema.Json, Schema.Json, never, never>, Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
         readonly reason: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unauthorized", {
             readonly code: Schema.Literals<readonly ["missing_credentials", "invalid_credentials", "expired", "access_denied", "outcome_access_denied", "reauthorization_unavailable"]>;
         }>, Schema.TaggedStruct<"InvalidInput", {
@@ -102,7 +88,6 @@ declare const make: (engine: Engine, actors: ReadonlyArray<AnyActor>, sessions:
         readonly retryAfter: Schema.optionalKey<Schema.Finite>;
     }>, never, never>>, Schema.Never, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
         readonly id: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-        readonly params: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     }>, import("effect/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
         readonly kind: Schema.Literal<"Frame">;
         readonly version: Schema.Finite;
@@ -157,10 +142,7 @@ declare const make: (engine: Engine, actors: ReadonlyArray<AnyActor>, sessions:
         readonly retryAfter: Schema.optionalKey<Schema.Finite>;
     }>, never, never>>, Schema.Never, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
         readonly id: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-        readonly from: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
-        readonly to: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
-        readonly limit: Schema.optional<Schema.Int>;
-        readonly reverse: Schema.optional<Schema.Boolean>;
+        readonly params: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     }>, import("effect/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
         readonly kind: Schema.Literal<"Frame">;
         readonly version: Schema.Finite;
@@ -215,8 +197,11 @@ declare const make: (engine: Engine, actors: ReadonlyArray<AnyActor>, sessions:
         readonly retryAfter: Schema.optionalKey<Schema.Finite>;
     }>, never, never>>, Schema.Never, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
         readonly id: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-        readonly presence: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-    }>, import("effect/rpc/RpcSchema").Stream<Schema.Literal<"joined">, Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
+        readonly from: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
+        readonly to: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
+        readonly limit: Schema.optional<Schema.Int>;
+        readonly reverse: Schema.optional<Schema.Boolean>;
+    }>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
         readonly reason: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unauthorized", {
             readonly code: Schema.Literals<readonly ["missing_credentials", "invalid_credentials", "expired", "access_denied", "outcome_access_denied", "reauthorization_unavailable"]>;
         }>, Schema.TaggedStruct<"InvalidInput", {
@@ -246,14 +231,35 @@ declare const make: (engine: Engine, actors: ReadonlyArray<AnyActor>, sessions:
         }>]>;
         readonly isRetryable: Schema.Boolean;
         readonly retryAfter: Schema.optionalKey<Schema.Finite>;
-    }>, never, never>>, Schema.Never, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
+    }>, never, never>, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
         readonly id: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-        readonly commandId: Schema.String;
-        readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-    }>, Schema.Struct<{
+        readonly from: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
+        readonly to: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
+        readonly limit: Schema.optional<Schema.Int>;
+        readonly reverse: Schema.optional<Schema.Boolean>;
+    }>, import("effect/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"Frame">;
+        readonly version: Schema.Finite;
         readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-        readonly replayed: Schema.Boolean;
-    }>, Schema.Union<readonly [Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"Patch">;
+        readonly version: Schema.Finite;
+        readonly ops: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+            readonly op: Schema.Literal<"add">;
+            readonly path: Schema.String;
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly description: Schema.optionalKey<Schema.String>;
+        }>, Schema.Struct<{
+            readonly op: Schema.Literal<"remove">;
+            readonly path: Schema.String;
+            readonly description: Schema.optionalKey<Schema.String>;
+        }>, Schema.Struct<{
+            readonly op: Schema.Literal<"replace">;
+            readonly path: Schema.String;
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly description: Schema.optionalKey<Schema.String>;
+        }>]>>;
+    }>]>, Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
         readonly reason: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unauthorized", {
             readonly code: Schema.Literals<readonly ["missing_credentials", "invalid_credentials", "expired", "access_denied", "outcome_access_denied", "reauthorization_unavailable"]>;
         }>, Schema.TaggedStruct<"InvalidInput", {
@@ -283,16 +289,10 @@ declare const make: (engine: Engine, actors: ReadonlyArray<AnyActor>, sessions:
         }>]>;
         readonly isRetryable: Schema.Boolean;
         readonly retryAfter: Schema.optionalKey<Schema.Finite>;
-    }>, never, never>, Schema.TaggedStruct<"ActionFailed", {
-        readonly error: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-        readonly replayed: Schema.Boolean;
-    }>]>, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
+    }>, never, never>>, Schema.Never, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
         readonly id: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-        readonly from: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
-        readonly to: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
-        readonly limit: Schema.optional<Schema.Int>;
-        readonly reverse: Schema.optional<Schema.Boolean>;
-    }>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
+        readonly presence: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>, import("effect/rpc/RpcSchema").Stream<Schema.Literal<"joined">, Schema.decodeTo<typeof ActorError, Schema.TaggedStruct<"ActorError", {
         readonly reason: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unauthorized", {
             readonly code: Schema.Literals<readonly ["missing_credentials", "invalid_credentials", "expired", "access_denied", "outcome_access_denied", "reauthorization_unavailable"]>;
         }>, Schema.TaggedStruct<"InvalidInput", {
@@ -322,7 +322,7 @@ declare const make: (engine: Engine, actors: ReadonlyArray<AnyActor>, sessions:
         }>]>;
         readonly isRetryable: Schema.Boolean;
         readonly retryAfter: Schema.optionalKey<Schema.Finite>;
-    }>, never, never>, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
+    }>, never, never>>, Schema.Never, typeof Authorization, never>, any> | Rpc.ToHandlerFn<Rpc.Rpc<string, Schema.Struct<{
         readonly where: Schema.$Record<Schema.String, Schema.Struct<{
             readonly eq: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
             readonly gt: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;

package/dist/snapshots/forks.js

@@ -18,6 +18,17 @@ export class ForkRefused extends Schema.TaggedError()("ForkRefused", {
 }) {
 }
 const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+/**
+ * A position no retained checkpoint can serve precedes the oldest one. When the newest position
+ * that checkpoint covers is older than the fork's retention cutoff, every position through it, the
+ * requested one included, is outside retention and its log prefix may already be trimmed, so the
+ * fork is refused for retention without reading the log. That time is the later of the shard's last
+ * action and the latest position any actor holds, because a fork installed into a shard records a
+ * position without advancing the shard's last action. The checkpoint's own contents decide this, on
+ * the same clock as the admission check, because which segments survive says nothing about
+ * retention once in-window segments are lost. Otherwise the log is read from its start, and a
+ * segment missing there is corruption.
+ */
 const forkOnce = (target, options, source = target.store) => Effect.gen(function* () {
     const { actor, from, at, grant } = options;
     const tenant = options.tenant ?? "default";
@@ -45,8 +56,10 @@ const forkOnce = (target, options, source = target.store) => Effect.gen(function
     const cache = new PageCache();
     const available = yield* source.history.checkpoints(shard);
     let base;
+    let oldestAt;
     for (const retained of available) {
         const decoded = Result.getOrThrow(Checkpoints.decode(yield* PagedCheckpoints.read(retained.statePages[0], source)));
+        oldestAt ??= decoded.actors.reduce((latest, candidate) => Math.max(latest, candidate.position?.at ?? 0), decoded.lastAt);
         const snapshot = decoded.actors.find((candidate) => candidate.actor === actor.name && same(candidate.key, from));
         const suitable = "offset" in at
             ? decoded.offset < at.offset
@@ -56,6 +69,8 @@ const forkOnce = (target, options, source = target.store) => Effect.gen(function
         if (suitable && (base === undefined || decoded.offset > base.offset))
             base = decoded;
     }
+    if (base === undefined && oldestAt !== undefined && oldestAt < cutoff)
+        return yield* ForkRefused.make({ reason: "retention" });
     const image = base === undefined ? Durable.empty(shard) : Checkpoints.restore(catalog, base, cache);
     const start = base?.offset ?? 0;
     const initial = image.actors.get(Durable.addressOf(actor.name, from));

package/dist/store/log.d.ts

@@ -38,6 +38,12 @@ export interface StoredSegment extends Segment {
 /** A retained checkpoint and its provider's last-modified time in epoch milliseconds. */
 export interface HistoryCheckpoint extends Manifest {
     readonly modified: number;
+    /**
+     * The checkpoint's offset precedes the oldest stored segment written within retention, or no
+     * stored segment was written within it. Lost in-window segments move that boundary later, so
+     * this does not prove the checkpoint's positions are outside retention.
+     */
+    readonly expired: boolean;
 }
 /**
  * The bucket log protocol. A segment is created once at `head + 1`; the

package/dist/store/log.js

@@ -248,7 +248,11 @@ export const bucketLog = (settings) => {
                     key,
                     reason: "checkpoint offset differs from its key",
                 });
-            retained.push({ ...manifest, modified });
+            retained.push({
+                ...manifest,
+                modified,
+                expired: window.first === undefined || offset < window.first,
+            });
         }
         return retained.reverse();
     }).pipe(Effect.catchTag("StorageUnavailable", (error) => Effect.fail(unavailable(error))));

package/package.json

@@ -1 +1 @@
-{"name":"@rikalabs/akter","version":"0.2.1","files":["dist","CHANGELOG.md","README.md","LICENSE","NOTICE"],"dependencies":{"@aws-sdk/client-s3":"3.1148.0","@effect/platform-node-shared":"4.0.3"},"peerDependencies":{"@effect/platform-bun":"^4.0.3","@effect/platform-node":"^4.0.3","effect":"^4.0.3"},"publishConfig":{"access":"public"},"description":"The framework for durable, stateful backends that power realtime apps, background work, and agents.","keywords":["actor-model","actors","agents","background-jobs","bun","durable","effect","effect-ts","realtime","stateful","transactions","workflows"],"homepage":"https://github.com/Rika-Labs/akter#readme","bugs":"https://github.com/Rika-Labs/akter/issues","license":"Apache-2.0","author":"Rika Labs","repository":{"type":"git","url":"git+https://github.com/Rika-Labs/akter.git","directory":"packages/akter"},"type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","default":"./dist/server.js"},"./client":{"types":"./dist/client/index.d.ts","default":"./dist/client/index.js"},"./testing":{"types":"./dist/testing/index.d.ts","default":"./dist/testing/index.js"},"./package.json":"./package.json"},"peerDependenciesMeta":{"@effect/platform-bun":{"optional":true},"@effect/platform-node":{"optional":true}},"engines":{"bun":">=1.4.2","node":">=24.0.0"}}
+{"name":"@rikalabs/akter","version":"0.2.2","files":["dist","CHANGELOG.md","README.md","LICENSE","NOTICE"],"dependencies":{"@aws-sdk/client-s3":"3.1148.0","@effect/platform-node-shared":"4.0.3"},"peerDependencies":{"@effect/platform-bun":"^4.0.3","@effect/platform-node":"^4.0.3","effect":"^4.0.3"},"publishConfig":{"access":"public"},"description":"The framework for durable, stateful backends that power realtime apps, background work, and agents.","keywords":["actor-model","actors","agents","background-jobs","bun","durable","effect","effect-ts","realtime","stateful","transactions","workflows"],"homepage":"https://github.com/Rika-Labs/akter#readme","bugs":"https://github.com/Rika-Labs/akter/issues","license":"Apache-2.0","author":"Rika Labs","repository":{"type":"git","url":"git+https://github.com/Rika-Labs/akter.git","directory":"packages/akter"},"type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","default":"./dist/server.js"},"./client":{"types":"./dist/client/index.d.ts","default":"./dist/client/index.js"},"./testing":{"types":"./dist/testing/index.d.ts","default":"./dist/testing/index.js"},"./package.json":"./package.json"},"peerDependenciesMeta":{"@effect/platform-bun":{"optional":true},"@effect/platform-node":{"optional":true}},"engines":{"bun":">=1.4.2","node":">=24.0.0"}}