@rikalabs/akter 0.1.0-alpha.0

package/dist/identity/caller.d.ts

@@ -0,0 +1,105 @@
+import { Context, Option, Schema } from "effect";
+/** The authenticated identity a request acts as: the `subject` its credentials name. */
+export declare const Principal: Schema.Struct<{
+    readonly subject: Schema.NonEmptyString;
+}>;
+/** The identity a request acts as. */
+export type Principal = typeof Principal.Type;
+/** Names one actor: the `tenant` that owns it, its definition name as `actor`, and its `id`. */
+export declare const ActorRef: Schema.Struct<{
+    readonly tenant: Schema.NonEmptyString;
+    readonly actor: Schema.NonEmptyString;
+    readonly id: Schema.NonEmptyString;
+}>;
+/** The identity of one actor. */
+export type ActorRef = typeof ActorRef.Type;
+/** A caller authenticated as the principal `subject`. */
+export declare const User: Schema.TaggedStruct<"User", {
+    readonly subject: Schema.NonEmptyString;
+}>;
+/** A caller that presented no credentials, as `Actor.auth.none` resolves every served request. */
+export declare const Anonymous: Schema.TaggedStruct<"Anonymous", {}>;
+/** Where a minted actor id came from: the minting command and its position in that turn. */
+export declare const MintProof: Schema.Struct<{
+    readonly commandId: Schema.String;
+    readonly ordinal: Schema.Int;
+}>;
+/** Proof that a minted actor id was derived by a parent's turn. */
+export type MintProof = typeof MintProof.Type;
+/**
+ * A caller the framework creates for its own deliveries, and the caller of
+ * code that runs in the application's own process. `source` names the
+ * mechanism (the process itself, an actor's intent, a timer, cron, a workflow,
+ * a job route, or a subscription), `ref` the actor that sent it, and
+ * `onBehalfOf` the principal of the turn that caused it. `mint` is set only on
+ * a minted child's creating intent, and proves the child's id was derived by
+ * its parent.
+ */
+export declare const System: Schema.TaggedStruct<"System", {
+    readonly source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription"]>;
+    readonly ref: Schema.optional<Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>>;
+    readonly onBehalfOf: Schema.optional<Schema.Struct<{
+        readonly subject: Schema.NonEmptyString;
+    }>>;
+    readonly mint: Schema.optional<Schema.Struct<{
+        readonly commandId: Schema.String;
+        readonly ordinal: Schema.Int;
+    }>>;
+}>;
+/** Who is calling: a `User`, `Anonymous`, or `System`. Tagged on `_tag`; `Caller.match` is exhaustive. */
+export declare const Caller: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"User", {
+    readonly subject: Schema.NonEmptyString;
+}>, Schema.TaggedStruct<"Anonymous", {}>, Schema.TaggedStruct<"System", {
+    readonly source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription"]>;
+    readonly ref: Schema.optional<Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>>;
+    readonly onBehalfOf: Schema.optional<Schema.Struct<{
+        readonly subject: Schema.NonEmptyString;
+    }>>;
+    readonly mint: Schema.optional<Schema.Struct<{
+        readonly commandId: Schema.String;
+        readonly ordinal: Schema.Int;
+    }>>;
+}>]>;
+/** A `User`, `Anonymous`, or `System` caller. */
+export type Caller = typeof Caller.Type;
+/**
+ * The ambient caller. Code running in the application's own process, outside
+ * any turn and not through `Actor.serve`, is the trusted `System` caller with
+ * source `"process"`; the transport sets it for a served request, and
+ * `Actor.as(caller)` scopes another around an Effect.
+ */
+export declare const CurrentCaller: Context.Reference<{
+    readonly _tag: "Anonymous";
+} | {
+    readonly _tag: "System";
+    readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+    readonly ref?: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    } | undefined;
+    readonly onBehalfOf?: {
+        readonly subject: string;
+    } | undefined;
+    readonly mint?: {
+        readonly commandId: string;
+        readonly ordinal: number;
+    } | undefined;
+} | {
+    readonly _tag: "User";
+    readonly subject: string;
+}>;
+/** The ambient tenant, `"default"` unless the transport sets one for a served request or `Actor.tenant(tenant)` scopes another around an Effect. */
+export declare const Tenant: Context.Reference<string>;
+/** The principal a caller acts as: a user's own, or the one a system caller acts on behalf of; none otherwise. */
+export declare const principal: (caller: Caller) => Option.Option<Principal>;
+/** A string that is equal for two callers exactly when they are the same caller, mint proof included. */
+export declare const callerKey: (caller: Caller) => string;

package/dist/identity/caller.js

@@ -0,0 +1,68 @@
+import { Context, Option, Schema } from "effect";
+/** The authenticated identity a request acts as: the `subject` its credentials name. */
+export const Principal = Schema.Struct({ subject: Schema.NonEmptyString });
+/** Names one actor: the `tenant` that owns it, its definition name as `actor`, and its `id`. */
+export const ActorRef = Schema.Struct({
+    tenant: Schema.NonEmptyString,
+    actor: Schema.NonEmptyString,
+    id: Schema.NonEmptyString,
+});
+/** A caller authenticated as the principal `subject`. */
+export const User = Schema.TaggedStruct("User", { subject: Schema.NonEmptyString });
+/** A caller that presented no credentials, as `Actor.auth.none` resolves every served request. */
+export const Anonymous = Schema.TaggedStruct("Anonymous", {});
+/** Where a minted actor id came from: the minting command and its position in that turn. */
+export const MintProof = Schema.Struct({
+    commandId: Schema.String,
+    ordinal: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+});
+/**
+ * A caller the framework creates for its own deliveries, and the caller of
+ * code that runs in the application's own process. `source` names the
+ * mechanism (the process itself, an actor's intent, a timer, cron, a workflow,
+ * a job route, or a subscription), `ref` the actor that sent it, and
+ * `onBehalfOf` the principal of the turn that caused it. `mint` is set only on
+ * a minted child's creating intent, and proves the child's id was derived by
+ * its parent.
+ */
+export const System = Schema.TaggedStruct("System", {
+    source: Schema.Literals(["process", "actor", "timer", "cron", "workflow", "job", "subscription"]),
+    ref: Schema.optional(ActorRef),
+    onBehalfOf: Schema.optional(Principal),
+    mint: Schema.optional(MintProof),
+});
+/** Who is calling: a `User`, `Anonymous`, or `System`. Tagged on `_tag`; `Caller.match` is exhaustive. */
+export const Caller = Schema.Union([User, Anonymous, System]).pipe(Schema.toTaggedUnion("_tag"));
+/**
+ * The ambient caller. Code running in the application's own process, outside
+ * any turn and not through `Actor.serve`, is the trusted `System` caller with
+ * source `"process"`; the transport sets it for a served request, and
+ * `Actor.as(caller)` scopes another around an Effect.
+ */
+export const CurrentCaller = Context.Reference("akter/CurrentCaller", {
+    defaultValue: () => System.make({ source: "process" }),
+});
+/** The ambient tenant, `"default"` unless the transport sets one for a served request or `Actor.tenant(tenant)` scopes another around an Effect. */
+export const Tenant = Context.Reference("akter/Tenant", {
+    defaultValue: () => "default",
+});
+/** The principal a caller acts as: a user's own, or the one a system caller acts on behalf of; none otherwise. */
+export const principal = (caller) => Caller.match(caller, {
+    User: ({ subject }) => Option.some(Principal.make({ subject })),
+    Anonymous: () => Option.none(),
+    System: ({ onBehalfOf }) => Option.fromUndefinedOr(onBehalfOf),
+});
+/** A string that is equal for two callers exactly when they are the same caller, mint proof included. */
+export const callerKey = (caller) => JSON.stringify(Caller.match(caller, {
+    User: ({ subject }) => ["User", subject],
+    Anonymous: () => ["Anonymous"],
+    System: ({ source, ref, onBehalfOf, mint }) => {
+        const key = [
+            "System",
+            source,
+            ref === undefined ? null : [ref.tenant, ref.actor, ref.id],
+            onBehalfOf?.subject ?? null,
+        ];
+        return mint === undefined ? key : [...key, [mint.commandId, mint.ordinal]];
+    },
+}));

package/dist/identity/child.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The id of a parent-placed actor: `c1.<byte length of parent>.<parent>.<local>`.
+ * The length prefix keeps the form unambiguous when the parent id contains
+ * `.` or is itself a child id, so routing never needs a lookup.
+ */
+export declare const childId: ({ parent, local }: {
+    readonly parent: string;
+    readonly local: string;
+}) => string;
+/**
+ * Splits a child id into its parent and local parts, or `undefined` when it is
+ * not one. The parent must end on a character boundary and be followed by
+ * `.`, and only the canonical `childId` form of its parts is accepted.
+ */
+export declare const parseChildId: (id: string) => {
+    readonly parent: string;
+    readonly local: string;
+} | undefined;

package/dist/identity/child.js

@@ -0,0 +1,39 @@
+const utf8 = new TextEncoder();
+const strict = new TextDecoder("utf-8", { fatal: true });
+const PREFIX = "c1.";
+/**
+ * A decimal byte count with no leading zero, then `.`. Every `childId` output
+ * parses, including one with an empty part: the parent's and child's key
+ * schemas decide whether a part is valid.
+ */
+const LENGTH = /^(?:0|[1-9][0-9]{0,9})\./;
+/**
+ * The id of a parent-placed actor: `c1.<byte length of parent>.<parent>.<local>`.
+ * The length prefix keeps the form unambiguous when the parent id contains
+ * `.` or is itself a child id, so routing never needs a lookup.
+ */
+export const childId = ({ parent, local }) => `${PREFIX}${utf8.encode(parent).byteLength}.${parent}.${local}`;
+/**
+ * Splits a child id into its parent and local parts, or `undefined` when it is
+ * not one. The parent must end on a character boundary and be followed by
+ * `.`, and only the canonical `childId` form of its parts is accepted.
+ */
+export const parseChildId = (id) => {
+    if (!id.startsWith(PREFIX))
+        return undefined;
+    const length = LENGTH.exec(id.slice(PREFIX.length))?.[0];
+    if (length === undefined)
+        return undefined;
+    const bytes = utf8.encode(id.slice(PREFIX.length + length.length));
+    const size = Number(length.slice(0, -1));
+    if (bytes.byteLength < size + 1 || bytes[size] !== 0x2e)
+        return undefined;
+    try {
+        const parent = strict.decode(bytes.subarray(0, size));
+        const local = strict.decode(bytes.subarray(size + 1));
+        return childId({ parent, local }) === id ? { parent, local } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/identity/command.d.ts

@@ -0,0 +1,19 @@
+import { Context, Schema } from "effect";
+/**
+ * A client-issued command id: `v1.<issuedAt>.<expiresAt>.<uuid v4>`, with both
+ * times in epoch milliseconds on the database clock.
+ */
+export declare const CommandId: Schema.String;
+/** The explicit command id for the command calls it is provided to, set by `Actor.commandId(id)`; undefined lets each call mint its own. */
+export declare const CurrentCommandId: Context.Reference<string | undefined>;
+/**
+ * Every id a receipt may carry: an external id, or a framework delivery id
+ * derived from the durable record it delivers, whose version-8 digest no
+ * caller can present because external admission accepts only version 4.
+ */
+export declare const InternalCommandId: Schema.String;
+/** The issue and expiry times, in epoch milliseconds, encoded in a command id. */
+export declare const commandTimes: (id: string) => {
+    issuedAt: number;
+    expiresAt: number;
+};

package/dist/identity/command.js

@@ -0,0 +1,21 @@
+import { Context, Schema } from "effect";
+/**
+ * A client-issued command id: `v1.<issuedAt>.<expiresAt>.<uuid v4>`, with both
+ * times in epoch milliseconds on the database clock.
+ */
+export const CommandId = Schema.String.check(Schema.isPattern(/^v1\.[1-9]\d{0,14}\.[1-9]\d{0,14}\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/));
+/** The explicit command id for the command calls it is provided to, set by `Actor.commandId(id)`; undefined lets each call mint its own. */
+export const CurrentCommandId = Context.Reference("akter/CurrentCommandId", {
+    defaultValue: () => undefined,
+});
+/**
+ * Every id a receipt may carry: an external id, or a framework delivery id
+ * derived from the durable record it delivers, whose version-8 digest no
+ * caller can present because external admission accepts only version 4.
+ */
+export const InternalCommandId = Schema.String.check(Schema.isPattern(/^v1\.[1-9]\d{0,14}\.[1-9]\d{0,14}\.[0-9a-f]{8}-[0-9a-f]{4}-[48][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/));
+/** The issue and expiry times, in epoch milliseconds, encoded in a command id. */
+export const commandTimes = (id) => {
+    const parts = InternalCommandId.make(id).split(".");
+    return { issuedAt: Number(parts[1]), expiresAt: Number(parts[2]) };
+};

package/dist/identity/connection.d.ts

@@ -0,0 +1,24 @@
+import { Context, Effect } from "effect";
+export interface ConnectionCommands {
+    /** Hex of 32 random bytes the holder minted at open; never stored or shown to handlers. */
+    readonly secret: string;
+    readonly seq: number;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+}
+/** Mints the id of one call from a connection handler, given its target actor key and command tag. */
+export declare const CurrentConnectionCommands: Context.Reference<((target: string, command: string) => Effect.Effect<string>) | undefined>;
+/**
+ * The id of the `index`th call a connection handler makes while handling frame
+ * `seq`: HMAC-SHA256 of the call under the connection's secret, shaped as a
+ * version-4 UUID so it matches every other command id. The call's parts are
+ * length-prefixed before hashing, so no two calls encode to the same message.
+ */
+export declare const connectionCommandId: ({ commands, index, target, command, }: {
+    readonly commands: ConnectionCommands;
+    readonly index: number;
+    readonly target: string;
+    readonly command: string;
+}) => Effect.Effect<string, never, never>;
+/** Hex-encodes the random bytes a holder mints as a connection's `ConnectionCommands.secret`. */
+export declare const connectionSecret: (bytes: Uint8Array) => string;

package/dist/identity/connection.js

@@ -0,0 +1,29 @@
+import { Context, Effect } from "effect";
+/** Mints the id of one call from a connection handler, given its target actor key and command tag. */
+export const CurrentConnectionCommands = Context.Reference("akter/CurrentConnectionCommands", { defaultValue: () => undefined });
+const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+const fromHex = (value) => Uint8Array.from(value.match(/../g) ?? [], (pair) => Number.parseInt(pair, 16));
+/**
+ * The id of the `index`th call a connection handler makes while handling frame
+ * `seq`: HMAC-SHA256 of the call under the connection's secret, shaped as a
+ * version-4 UUID so it matches every other command id. The call's parts are
+ * length-prefixed before hashing, so no two calls encode to the same message.
+ */
+export const connectionCommandId = ({ commands, index, target, command, }) => Effect.gen(function* () {
+    const subtle = globalThis.crypto.subtle;
+    const key = yield* Effect.promise(() => subtle.importKey("raw", fromHex(commands.secret), { name: "HMAC", hash: "SHA-256" }, false, [
+        "sign",
+    ]));
+    const message = new TextEncoder().encode([String(commands.seq), String(index), target, command]
+        .map((part) => `${part.length}:${part}`)
+        .join(""));
+    const digest = new Uint8Array(yield* Effect.promise(() => subtle.sign("HMAC", key, message)));
+    const bytes = digest.slice(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const raw = hex(bytes);
+    const uuid = `${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20)}`;
+    return `v1.${commands.issuedAt}.${commands.expiresAt}.${uuid}`;
+});
+/** Hex-encodes the random bytes a holder mints as a connection's `ConnectionCommands.secret`. */
+export const connectionSecret = (bytes) => hex(bytes);

package/dist/identity/content.d.ts

@@ -0,0 +1,18 @@
+import { Schema } from "effect";
+/**
+ * A reference to uploaded content. `grant` is the capability: it is bound to
+ * the tenant, the hash, and the size, and expires. Knowing only the hash grants nothing.
+ */
+export declare const ContentRef: Schema.Struct<{
+    readonly hash: Schema.String;
+    readonly size: Schema.Int;
+    readonly grant: Schema.String;
+}>;
+/** An uploaded content's hash, size, and grant. */
+export type ContentRef = typeof ContentRef.Type;
+/** One reference an actor holds under a content blob. */
+export interface ContentEntry {
+    readonly name: string;
+    readonly hash: string;
+    readonly size: number;
+}

package/dist/identity/content.js

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+/** Hex SHA-256 of a content's bytes, computed by the server, never supplied by a client. */
+const ContentHash = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/u));
+/**
+ * A reference to uploaded content. `grant` is the capability: it is bound to
+ * the tenant, the hash, and the size, and expires. Knowing only the hash grants nothing.
+ */
+export const ContentRef = Schema.Struct({
+    hash: ContentHash,
+    size: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    grant: Schema.String,
+});

package/dist/identity/digest.d.ts

@@ -0,0 +1,4 @@
+/** A browser-safe SHA-256 accumulator, with Bun's native implementation when available. */
+export declare const sha256Hasher: () => Bun.CryptoHasher | import("@noble/hashes/sha2.js")._SHA256;
+/** Stable SHA-256 bytes shared by runtime, content references and fleet definitions. */
+export declare const sha256Bytes: (bytes: Uint8Array) => Buffer<ArrayBufferLike> | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);

package/dist/identity/digest.js

@@ -0,0 +1,5 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+/** A browser-safe SHA-256 accumulator, with Bun's native implementation when available. */
+export const sha256Hasher = () => globalThis.Bun === undefined ? sha256.create() : new globalThis.Bun.CryptoHasher("sha256");
+/** Stable SHA-256 bytes shared by runtime, content references and fleet definitions. */
+export const sha256Bytes = (bytes) => sha256Hasher().update(bytes).digest();

package/dist/identity/execution.d.ts

@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+import { InvalidExecutionId, InvalidExecutionKey } from "../errors/workflow.ts";
+/** Everything an execution id names: its owner, its workflow member, and its key. */
+interface Execution {
+    readonly tenant: string;
+    readonly actor: string;
+    readonly id: string;
+    readonly workflow: string;
+    readonly key: string;
+}
+/** Fails `InvalidExecutionKey` unless `key` is 1 to `MAX_KEY_BYTES` UTF-8 bytes. */
+export declare const checkExecutionKey: (key: string) => Effect.Effect<void, never, never> | Effect.Effect<never, InvalidExecutionKey, never>;
+/**
+ * The stable id of one execution: every part that identifies it, so an id
+ * routes to its owner without a lookup. The deployment is the database, so
+ * it is not encoded. Every other part is bounded by its own schema, so only a
+ * key that overflows `MAX_EXECUTION_ID_BYTES` fails `InvalidExecutionKey`.
+ */
+export declare const encodeExecutionId: (execution: Execution) => Effect.Effect<string, InvalidExecutionKey, never>;
+/**
+ * Decodes an execution id; a malformed or non-`w1.` id fails
+ * `InvalidExecutionId`. Only the canonical encoding is an id, so two strings
+ * never name one execution.
+ */
+export declare const decodeExecutionId: (executionId: string) => Effect.Effect<{
+    tenant: string;
+    actor: string;
+    id: string;
+    workflow: string;
+    key: string;
+}, InvalidExecutionId, never>;
+export {};

package/dist/identity/execution.js

@@ -0,0 +1,63 @@
+import { Effect, Result, Schema } from "effect";
+import { Base64Url } from "effect/encoding";
+import { InvalidExecutionId, InvalidExecutionKey } from "../errors/workflow.js";
+/** Longest workflow key, in UTF-8 bytes. */
+const MAX_KEY_BYTES = 256;
+/** Longest execution id, in bytes. */
+const MAX_EXECUTION_ID_BYTES = 1024;
+const utf8 = new TextEncoder();
+const Parts = Schema.Tuple([
+    Schema.NonEmptyString,
+    Schema.NonEmptyString,
+    Schema.NonEmptyString,
+    Schema.NonEmptyString,
+    Schema.NonEmptyString,
+]);
+const PartsJson = Schema.fromJsonString(Parts);
+const decodeParts = Schema.decodeResult(PartsJson);
+const encodeParts = (parts) => JSON.stringify(parts);
+/** Fails `InvalidExecutionKey` unless `key` is 1 to `MAX_KEY_BYTES` UTF-8 bytes. */
+export const checkExecutionKey = (key) => {
+    const bytes = utf8.encode(key).byteLength;
+    return bytes === 0 || bytes > MAX_KEY_BYTES
+        ? Effect.fail(InvalidExecutionKey.make({ bytes }))
+        : Effect.void;
+};
+/**
+ * The stable id of one execution: every part that identifies it, so an id
+ * routes to its owner without a lookup. The deployment is the database, so
+ * it is not encoded. Every other part is bounded by its own schema, so only a
+ * key that overflows `MAX_EXECUTION_ID_BYTES` fails `InvalidExecutionKey`.
+ */
+export const encodeExecutionId = (execution) => Effect.gen(function* () {
+    yield* checkExecutionKey(execution.key);
+    const { tenant, actor, id, workflow, key } = execution;
+    const executionId = `w1.${Base64Url.encode(encodeParts([tenant, actor, id, workflow, key]))}`;
+    if (utf8.encode(executionId).byteLength > MAX_EXECUTION_ID_BYTES)
+        return yield* InvalidExecutionKey.make({ bytes: utf8.encode(key).byteLength });
+    return executionId;
+});
+/**
+ * Decodes an execution id; a malformed or non-`w1.` id fails
+ * `InvalidExecutionId`. Only the canonical encoding is an id, so two strings
+ * never name one execution.
+ */
+export const decodeExecutionId = (executionId) => Effect.gen(function* () {
+    const invalid = InvalidExecutionId.make({ executionId });
+    if (!executionId.startsWith("w1.") ||
+        utf8.encode(executionId).byteLength > MAX_EXECUTION_ID_BYTES)
+        return yield* invalid;
+    const json = Base64Url.decodeString(executionId.slice(3));
+    if (Result.isFailure(json))
+        return yield* invalid;
+    const parts = decodeParts(json.success);
+    if (Result.isFailure(parts))
+        return yield* invalid;
+    const [tenant, actor, id, workflow, key] = parts.success;
+    if (utf8.encode(key).byteLength > MAX_KEY_BYTES)
+        return yield* invalid;
+    const canonical = `w1.${Base64Url.encode(encodeParts(parts.success))}`;
+    if (canonical !== executionId)
+        return yield* invalid;
+    return { tenant, actor, id, workflow, key };
+});

package/dist/identity/mint.d.ts

@@ -0,0 +1,51 @@
+import { Crypto, Effect } from "effect";
+import { type ActorRef } from "./caller.ts";
+/** What a minted id is derived from: the minting parent, the command and position in its turn, and the child's actor type. */
+export interface MintInput {
+    /** The minting parent; a singleton parent's id is the empty string. */
+    readonly parent: ActorRef;
+    readonly commandId: string;
+    /** How many mints the turn made before this one. */
+    readonly ordinal: number;
+    /** The child's actor type. */
+    readonly child: string;
+}
+/** True for the lowercase UUIDv8 form `turn.mint` produces. */
+export declare const isMintedId: (id: string) => boolean;
+/** Length-prefixed UTF-8 fields the minted id digests, in order. */
+export declare const mintPreimage: ({ parent, commandId, ordinal, child }: MintInput) => Uint8Array<ArrayBuffer>;
+/** The UUIDv8 a parent turn mints for `child` at `ordinal`: the first 16 SHA-256 bytes of its preimage. */
+export declare const deriveMintId: (input: MintInput) => Effect.Effect<string, never, Crypto.Crypto>;
+/**
+ * True when `caller` is the framework's creating intent for the minted actor
+ * `target`. A parent-placed target, whose parent type is `parent`, is minted
+ * only by the parent its id names, and only its local part is derived. A
+ * singleton parent digests an empty id, and its ref alone cannot tell it from
+ * a keyed parent whose id is `singleton`, so both digests are accepted; one
+ * actor type is never both.
+ */
+export declare const provesMint: (caller: {
+    readonly _tag: "Anonymous";
+} | {
+    readonly _tag: "System";
+    readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+    readonly ref?: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    } | undefined;
+    readonly onBehalfOf?: {
+        readonly subject: string;
+    } | undefined;
+    readonly mint?: {
+        readonly commandId: string;
+        readonly ordinal: number;
+    } | undefined;
+} | {
+    readonly _tag: "User";
+    readonly subject: string;
+}, target: {
+    readonly tenant: string;
+    readonly actor: string;
+    readonly id: string;
+}, parent?: string | undefined) => Effect.Effect<boolean, never, Crypto.Crypto>;

package/dist/identity/mint.js

@@ -0,0 +1,76 @@
+import { Crypto, Effect, Schema } from "effect";
+import { System } from "./caller.js";
+import { parseChildId } from "./child.js";
+/**
+ * The digest's domain string. It predates the Akter name and stays as it is,
+ * because every minted id already stored was derived with it.
+ */
+const DOMAIN = "durable-actors/mint/v1";
+const SINGLETON_ID = "singleton";
+const utf8 = new TextEncoder();
+const MINTED = /^[0-9a-f]{8}-[0-9a-f]{4}-8[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+/** True for the lowercase UUIDv8 form `turn.mint` produces. */
+export const isMintedId = (id) => MINTED.test(id);
+/** Length-prefixed UTF-8 fields the minted id digests, in order. */
+export const mintPreimage = ({ parent, commandId, ordinal, child }) => {
+    const fields = [
+        DOMAIN,
+        parent.tenant,
+        parent.actor,
+        parent.id,
+        commandId,
+        String(ordinal),
+        child,
+    ].map((field) => utf8.encode(field));
+    const bytes = new Uint8Array(fields.reduce((size, field) => size + 4 + field.byteLength, 0));
+    const view = new DataView(bytes.buffer);
+    let offset = 0;
+    for (const field of fields) {
+        view.setUint32(offset, field.byteLength);
+        bytes.set(field, offset + 4);
+        offset += 4 + field.byteLength;
+    }
+    return bytes;
+};
+/** The UUIDv8 a parent turn mints for `child` at `ordinal`: the first 16 SHA-256 bytes of its preimage. */
+export const deriveMintId = Effect.fnUntraced(function* (input) {
+    const digest = yield* (yield* Crypto.Crypto)
+        .digest("SHA-256", mintPreimage(input))
+        .pipe(Effect.orDie);
+    const bytes = digest.slice(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x80;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+});
+/**
+ * True when `caller` is the framework's creating intent for the minted actor
+ * `target`. A parent-placed target, whose parent type is `parent`, is minted
+ * only by the parent its id names, and only its local part is derived. A
+ * singleton parent digests an empty id, and its ref alone cannot tell it from
+ * a keyed parent whose id is `singleton`, so both digests are accepted; one
+ * actor type is never both.
+ */
+export const provesMint = Effect.fnUntraced(function* (caller, target, parent) {
+    if (!Schema.is(System)(caller) ||
+        caller.source === "cron" ||
+        caller.source === "workflow" ||
+        caller.source === "job")
+        return false;
+    const { ref, mint } = caller;
+    if (ref === undefined || mint === undefined || ref.tenant !== target.tenant)
+        return false;
+    const parts = parent === undefined ? undefined : parseChildId(target.id);
+    if (parent !== undefined && (parts?.parent !== ref.id || ref.actor !== parent))
+        return false;
+    const id = parts?.local ?? target.id;
+    const derives = (minter) => deriveMintId({
+        parent: minter,
+        commandId: mint.commandId,
+        ordinal: mint.ordinal,
+        child: target.actor,
+    });
+    if ((yield* derives(ref)) === id)
+        return true;
+    return ref.id === SINGLETON_ID && (yield* derives({ ...ref, id: "" })) === id;
+});

package/dist/identity/version.d.ts

@@ -0,0 +1,2 @@
+/** Whether `value` is a commit version token: decimal digits without leading zeros, as `durable-version` is written. */
+export declare const isVersion: (value: string) => boolean;

package/dist/identity/version.js

@@ -0,0 +1,3 @@
+const TOKEN = /^(0|[1-9]\d*)$/;
+/** Whether `value` is a commit version token: decimal digits without leading zeros, as `durable-version` is written. */
+export const isVersion = (value) => TOKEN.test(value);