@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/role.d.ts

@@ -0,0 +1,61 @@
+import { type ScopedPermission } from "./permissions.js";
+export declare const RoleTypeId: unique symbol;
+/**
+ * A business role: a named set of permissions. Members are given roles from the CLI or the app; an
+ * API key holds exactly the roles it was created with.
+ */
+export interface Role<Name extends string = string> {
+    readonly [RoleTypeId]: typeof RoleTypeId;
+    readonly name: Name;
+    readonly description: string;
+    /**
+     * What the role may do, as `<entity>:<verb>` permissions: `lead:read`, `lead:changeStatus`. `*`
+     * stands for any entity or any verb: `lead:*`, `*:read`, `*:*`. Scoped permissions are listed
+     * too, once each, so that whatever reads permissions sees every one the role holds.
+     */
+    readonly permissions: ReadonlyArray<string>;
+    /**
+     * The scoped permissions, with their `where`, in declaration order. A permission the role also
+     * grants unscoped is not scoped: the unscoped grant covers every record.
+     */
+    readonly scopes: ReadonlyArray<ScopedPermission>;
+    /**
+     * Scoped entries the role also grants unscoped by the same permission, dropped from `scopes`;
+     * kept only for `check` to report. Never in the manifest.
+     */
+    readonly unusedScopes?: ReadonlyArray<ScopedPermission>;
+}
+/** A role permission: `<entity>:<verb>`, or a scoped one, `{ permission, where }`. */
+export type RolePermission = string | ScopedPermission;
+export interface RoleOptions {
+    readonly description: string;
+    /**
+     * At least one permission; `check` refuses a role without any. A string grants every record; a
+     * {@link ScopedPermission} only those its `where` matches.
+     */
+    readonly permissions: ReadonlyArray<RolePermission>;
+}
+/**
+ * The permissions and scopes of a role's entries. A string is kept as written, even twice, so that
+ * an ontology without scoped permissions lists exactly what it declares; a scoped entry adds its
+ * permission once, and is dropped into `unusedScopes` when the role grants the same permission
+ * unscoped, in any case. Anything else is kept for `check` to report.
+ */
+export declare function rolePermissions(entries: ReadonlyArray<RolePermission>): {
+    readonly permissions: ReadonlyArray<string>;
+    readonly scopes: ReadonlyArray<ScopedPermission>;
+    readonly unusedScopes?: ReadonlyArray<ScopedPermission>;
+};
+/**
+ * A role's entries rebuilt from its permissions and scopes, as a manifest lists them: each scoped
+ * permission at its place, once per scope. A scope whose permission the list lacks comes last.
+ */
+export declare function roleEntries(permissions: ReadonlyArray<string>, scopes: ReadonlyArray<ScopedPermission>): ReadonlyArray<RolePermission>;
+export declare function role<const Name extends string>(name: Name, options: RoleOptions): Role<Name>;
+export declare function isRole(value: unknown): value is Role;
+/**
+ * The built-in role every active app user holds, with its default permissions. An ontology sets
+ * what members may do with `defineOntology({ member: { permissions } })`. Service principals hold
+ * only the roles they were given.
+ */
+export declare const member: Role<"member">;

package/dist/role.js

@@ -0,0 +1,76 @@
+import { MEMBER_ROLE } from "./names.js";
+import { DEFAULT_MEMBER_PERMISSIONS, normalizePermission, } from "./permissions.js";
+export const RoleTypeId = Symbol.for("@segmentstream/ontology/Role");
+function isScoped(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The permissions and scopes of a role's entries. A string is kept as written, even twice, so that
+ * an ontology without scoped permissions lists exactly what it declares; a scoped entry adds its
+ * permission once, and is dropped into `unusedScopes` when the role grants the same permission
+ * unscoped, in any case. Anything else is kept for `check` to report.
+ */
+export function rolePermissions(entries) {
+    if (!Array.isArray(entries)) {
+        return { permissions: entries, scopes: [] };
+    }
+    const normalized = (value) => typeof value === "string" ? normalizePermission(value) : value;
+    const unscoped = new Set(entries.filter((entry) => !isScoped(entry)).map(normalized));
+    const permissions = [];
+    const scopes = [];
+    const unusedScopes = [];
+    for (const entry of entries) {
+        if (!isScoped(entry)) {
+            permissions.push(entry);
+        }
+        else if (unscoped.has(normalized(entry.permission))) {
+            unusedScopes.push(entry);
+        }
+        else {
+            if (!permissions.includes(entry.permission)) {
+                permissions.push(entry.permission);
+            }
+            scopes.push(entry);
+        }
+    }
+    return { permissions, scopes, ...(unusedScopes.length === 0 ? {} : { unusedScopes }) };
+}
+/**
+ * A role's entries rebuilt from its permissions and scopes, as a manifest lists them: each scoped
+ * permission at its place, once per scope. A scope whose permission the list lacks comes last.
+ */
+export function roleEntries(permissions, scopes) {
+    return [
+        ...permissions.flatMap((permission) => {
+            const own = scopes.filter((scope) => scope.permission === permission);
+            return own.length === 0 ? [permission] : own;
+        }),
+        ...scopes.filter((scope) => !permissions.includes(scope.permission)),
+    ];
+}
+// @legacy ontology.removed-allow-option
+/** Options removed from earlier releases, kept on the role so that `check` can explain them. */
+function removedOptions(options) {
+    return "allow" in options ? { allow: options.allow } : {};
+}
+export function role(name, options) {
+    return {
+        ...removedOptions(options),
+        [RoleTypeId]: RoleTypeId,
+        name,
+        description: options.description,
+        ...rolePermissions(options.permissions),
+    };
+}
+export function isRole(value) {
+    return typeof value === "object" && value !== null && RoleTypeId in value;
+}
+/**
+ * The built-in role every active app user holds, with its default permissions. An ontology sets
+ * what members may do with `defineOntology({ member: { permissions } })`. Service principals hold
+ * only the roles they were given.
+ */
+export const member = role(MEMBER_ROLE, {
+    description: "Every active app user.",
+    permissions: DEFAULT_MEMBER_PERMISSIONS,
+});

package/dist/runtime/action-deadlocks.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { type SqlError } from "effect/unstable/sql/SqlError";
+import { Conflict } from "../errors.js";
+/**
+ * Owns complete SQL transactions, never an aborted transaction's statements. The caller admits
+ * this entire effect once. Each body is built anew; only its successful attempt's state escapes.
+ */
+export declare function actionTransaction<A, E, R>(sql: Pick<SqlClient.SqlClient, "withTransaction">, body: () => Effect.Effect<A, E, R>, options: {
+    readonly qualified: string;
+    readonly actionId?: string;
+    readonly requestId?: string;
+    readonly retryOnDeadlock: boolean;
+    readonly handlerTimeoutMs: number;
+    /**
+     * Whether a cleanly rolled-back conflict may be answered as a retryable Conflict: true unless
+     * sending the request again would repeat an effect outside the transaction, such as a
+     * connection call in `prepare`. Absent means true.
+     */
+    readonly conflictRetryable?: boolean;
+}): Effect.Effect<A, E | SqlError | Conflict, R>;

package/dist/runtime/action-deadlocks.js

@@ -0,0 +1,130 @@
+import { randomInt } from "node:crypto";
+import { Cause, Clock, Duration, Effect, Exit } from "effect";
+import { isSqlError } from "effect/unstable/sql/SqlError";
+import { Conflict } from "../errors.js";
+import { captureRuntimeFailure } from "../internal/diagnostics.js";
+import { ActionTransactionDeadline } from "./action-transactions.js";
+const MAX_DEADLOCK_RETRIES = 2;
+const monotonicMillis = Clock.monotonicTimeNanos.pipe(Effect.map((nanos) => Number(nanos) / 1_000_000));
+/** A distinct failure prevents Effect from deduplicating equal body and cleanup SQL errors. */
+class AttemptFailure {
+    cause;
+    constructor(cause) {
+        this.cause = cause;
+    }
+}
+/**
+ * The SQLSTATE of the one original PostgreSQL failure, when it is a deadlock (`40P01`) or a
+ * serialization failure (`40001`) with no interruption or cleanup failure alongside it. Both mean
+ * PostgreSQL chose this transaction to roll back because of a concurrent one.
+ */
+function rolledBackConflictOf(cause) {
+    if (cause?.reasons.length !== 1) {
+        return undefined;
+    }
+    const reason = cause.reasons[0];
+    const error = reason._tag === "Fail" ? reason.error : reason._tag === "Die" ? reason.defect : undefined;
+    if (!isSqlError(error)) {
+        return undefined;
+    }
+    const driver = error.reason.cause;
+    const code = typeof driver === "object" && driver !== null && "code" in driver ? driver.code : undefined;
+    if (error.reason._tag === "DeadlockError" && code === "40P01") {
+        return "40P01";
+    }
+    return error.reason._tag === "SerializationError" && code === "40001" ? "40001" : undefined;
+}
+/** Only one original PostgreSQL deadlock, with no interruption or cleanup failure alongside it. */
+function deadlockOf(cause) {
+    return rolledBackConflictOf(cause) === "40P01";
+}
+/**
+ * Owns complete SQL transactions, never an aborted transaction's statements. The caller admits
+ * this entire effect once. Each body is built anew; only its successful attempt's state escapes.
+ */
+export function actionTransaction(sql, body, options) {
+    return Effect.gen(function* () {
+        let deadlineAt;
+        for (let retries = 0;; retries += 1) {
+            let failedBody;
+            const transaction = sql.withTransaction(Effect.gen(function* () {
+                const now = yield* monotonicMillis;
+                deadlineAt ??= now + options.handlerTimeoutMs;
+                const expired = Effect.logWarning("ontology.action.transaction_deadline").pipe(Effect.annotateLogs({ deadlineMs: options.handlerTimeoutMs }), Effect.andThen(Effect.die(new ActionTransactionDeadline(`${options.qualified} exceeded its transaction deadline.`))));
+                if (deadlineAt <= now) {
+                    return yield* expired;
+                }
+                return yield* Effect.suspend(body).pipe(Effect.timeoutOrElse({
+                    duration: Duration.millis(deadlineAt - now),
+                    orElse: () => expired,
+                }), Effect.catchCause((cause) => {
+                    failedBody = new AttemptFailure(cause);
+                    return Effect.fail(failedBody);
+                }));
+            }));
+            // Effect SQL finalizes uninterruptibly, including rollback and connection release. Only a
+            // body failure that survives finalization unchanged proves a completed, clean rollback.
+            // Acquisition, BEGIN, COMMIT and cleanup failures can never satisfy both checks.
+            const settled = yield* Effect.exit(transaction);
+            if (Exit.isSuccess(settled)) {
+                return settled.value;
+            }
+            const reasons = settled.cause.reasons;
+            const cleanRollback = reasons.length === 1 && reasons[0]._tag === "Fail" && reasons[0].error === failedBody;
+            const deadlock = deadlockOf(failedBody?.cause);
+            const conflict = cleanRollback && options.conflictRetryable !== false
+                ? rolledBackConflictOf(failedBody?.cause)
+                : undefined;
+            // Restore the exact original reasons, including defects/interruptions, alongside any
+            // transaction finalization failures. The private marker never reaches public diagnostics.
+            const cause = Cause.fromReasons(reasons.flatMap((reason) => reason._tag === "Fail" && reason.error instanceof AttemptFailure
+                ? reason.error.cause.reasons
+                : [reason]));
+            // A conflict PostgreSQL rolled back cleanly wrote nothing, so the caller may send the same
+            // request again: answer it as a retryable Conflict, and keep the original cause for operators.
+            // An action whose prepare called a connection is not: a resend would call it again.
+            const settle = () => conflict === undefined
+                ? Effect.failCause(cause)
+                : Effect.sync(() => captureRuntimeFailure(cause, {
+                    service: "ontology",
+                    boundary: "ontology.action.transaction_conflict",
+                    severity: "warning",
+                    action: options.qualified,
+                    actionId: options.actionId,
+                    requestId: options.requestId,
+                    retries,
+                    sqlState: conflict,
+                })).pipe(Effect.andThen(Effect.fail(new Conflict({
+                    entity: options.qualified.split(".")[0] ?? options.qualified,
+                    message: `${options.qualified} conflicted with a concurrent change and was rolled ` +
+                        "back; nothing was written. Send the same request again.",
+                    retryAfter: 1,
+                }))));
+            if (!options.retryOnDeadlock ||
+                retries >= MAX_DEADLOCK_RETRIES ||
+                !deadlock ||
+                !cleanRollback) {
+                return yield* settle();
+            }
+            const delayMs = randomInt(10, 51) * 2 ** retries;
+            const now = yield* monotonicMillis;
+            // Retry backoff and finalization consume the same budget as the first body. Do not replace
+            // the original deadlock when there is insufficient time for another attempt.
+            if (deadlineAt === undefined || deadlineAt - now <= delayMs) {
+                return yield* settle();
+            }
+            yield* Effect.sync(() => captureRuntimeFailure(cause, {
+                service: "ontology",
+                boundary: "ontology.action.deadlock_retry",
+                severity: "warning",
+                action: options.qualified,
+                actionId: options.actionId,
+                requestId: options.requestId,
+                retry: retries + 1,
+                delayMs,
+                sqlState: "40P01",
+            }));
+            yield* Effect.sleep(Duration.millis(delayMs));
+        }
+    });
+}

package/dist/runtime/action-transactions.d.ts

@@ -0,0 +1,35 @@
+import { Context, Effect } from "effect";
+/** Admission happens before reserving SQL connections; two pool slots remain for other work. */
+export declare const ACTION_TRANSACTION_LIMITS: {
+    readonly concurrency: 3;
+    readonly maxWaiting: 32;
+    readonly queueTimeoutMs: 5000;
+    readonly handlerTimeoutMs: 60000;
+    readonly statementTimeoutMs: 30000;
+    readonly lockTimeoutMs: 5000;
+};
+export interface ActionTransactionLimits {
+    readonly handlerTimeoutMs: number;
+    readonly statementTimeoutMs: number;
+    readonly lockTimeoutMs: number;
+}
+export declare class ActionTransactionDeadline extends Error {
+    readonly name = "ActionTransactionDeadline";
+}
+export declare class ActionAdmissionRejected extends Error {
+    readonly name = "ActionAdmissionRejected";
+}
+export interface ActionTransactionsService {
+    readonly limits: ActionTransactionLimits;
+    readonly admit: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+declare const ActionTransactions_base: Context.ServiceClass<ActionTransactions, "segmentstream/ontology/ActionTransactions", ActionTransactionsService>;
+/** Internal configuration and one admission gate per service instance, never per request. */
+export declare class ActionTransactions extends ActionTransactions_base {
+}
+export declare function makeActionTransactions(options?: ActionTransactionLimits & {
+    readonly concurrency: number;
+    readonly maxWaiting: number;
+    readonly queueTimeoutMs: number;
+}): ActionTransactionsService;
+export {};

package/dist/runtime/action-transactions.js

@@ -0,0 +1,54 @@
+import { Context, Duration, Effect, Exit, Semaphore } from "effect";
+/** Admission happens before reserving SQL connections; two pool slots remain for other work. */
+export const ACTION_TRANSACTION_LIMITS = {
+    concurrency: 3,
+    maxWaiting: 32,
+    queueTimeoutMs: 5_000,
+    handlerTimeoutMs: 60_000,
+    statementTimeoutMs: 30_000,
+    lockTimeoutMs: 5_000,
+};
+export class ActionTransactionDeadline extends Error {
+    name = "ActionTransactionDeadline";
+}
+export class ActionAdmissionRejected extends Error {
+    name = "ActionAdmissionRejected";
+}
+/** Internal configuration and one admission gate per service instance, never per request. */
+export class ActionTransactions extends Context.Service()("segmentstream/ontology/ActionTransactions") {
+}
+export function makeActionTransactions(options = ACTION_TRANSACTION_LIMITS) {
+    const permits = Semaphore.makeUnsafe(options.concurrency);
+    let waiting = 0;
+    let active = 0;
+    return {
+        limits: options,
+        admit: (effect) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+            const queuedAt = Date.now();
+            if (!(yield* permits.takeIfAvailable(1))) {
+                if (waiting >= options.maxWaiting) {
+                    yield* Effect.logWarning("ontology.action.admission_rejected").pipe(Effect.annotateLogs({ active, waiting, reason: "queue_full" }));
+                    return yield* Effect.die(new ActionAdmissionRejected("Action write queue is full."));
+                }
+                waiting += 1;
+                yield* restore(permits.take(1).pipe(Effect.timeoutOrElse({
+                    duration: Duration.millis(options.queueTimeoutMs),
+                    orElse: () => Effect.logWarning("ontology.action.admission_rejected").pipe(Effect.annotateLogs({ active, waiting, reason: "queue_timeout" }), Effect.andThen(Effect.die(new ActionAdmissionRejected("Action write admission timed out.")))),
+                }))).pipe(Effect.ensuring(Effect.sync(() => {
+                    waiting -= 1;
+                })));
+            }
+            active += 1;
+            const startedAt = Date.now();
+            return yield* restore(effect).pipe(Effect.onExit((exit) => Effect.logDebug("ontology.action.transaction_completed").pipe(Effect.annotateLogs({
+                active,
+                waiting,
+                queueMs: startedAt - queuedAt,
+                transactionMs: Date.now() - startedAt,
+                outcome: Exit.isSuccess(exit) ? "success" : "failure",
+            }))), Effect.ensuring(Effect.sync(() => {
+                active -= 1;
+            }).pipe(Effect.andThen(permits.release(1)))));
+        })),
+    };
+}

package/dist/runtime/agent-counters.d.ts

@@ -0,0 +1,26 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import type { AgentLimits, AgentLimitScope, AgentResolution, ResolveIdentityInput } from "../service/runtime-contract.js";
+/** Defaults shared by bot resolution and other trusted channel admission boundaries. */
+export declare const DEFAULT_AGENT_LIMITS: AgentLimits;
+/** Platform ceilings. Workspace policy can only lower these values. */
+export declare const PLATFORM_CHANNEL_LIMITS: AgentLimits;
+export declare function clampChannelLimits(input: ResolveIdentityInput["limits"]): AgentLimits;
+/** Only trusted runtimes submit limits; channel-app callers omit them and reuse the latest policy. */
+export declare function effectiveChannelLimits(sql: SqlClient.SqlClient, input?: ResolveIdentityInput["limits"]): Effect.Effect<AgentLimits, never, never>;
+type Limited = Extract<AgentResolution, {
+    status: "limited";
+}>;
+/** A failed send releases its claim; a lost process can be retried after a 30-second lease. */
+export declare function completeAgentLimitNotice(sql: SqlClient.SqlClient, input: {
+    readonly notificationId: string;
+    readonly delivered: boolean;
+}): Effect.Effect<boolean, never, never>;
+/** Count attempts durably; notify once per effective threshold within each fixed window. */
+export declare function countAgentAttempt(sql: SqlClient.SqlClient, input: {
+    readonly scope: AgentLimitScope;
+    readonly subject: string;
+    readonly window: "minute" | "hour" | "day";
+    readonly limit: number;
+}): Effect.Effect<Limited | undefined>;
+export {};

package/dist/runtime/agent-counters.js

@@ -0,0 +1,98 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Schema } from "effect";
+import { AGENT_COUNTERS_TABLE, CHANNEL_LIMITS_TABLE } from "../migrate/storage.js";
+/** Defaults shared by bot resolution and other trusted channel admission boundaries. */
+export const DEFAULT_AGENT_LIMITS = Object.freeze({
+    perSender: Object.freeze({ turnsPerMinute: 6, turnsPerDay: 80 }),
+    newUsersPerHour: 30,
+    workspaceTurnsPerDay: 3000,
+});
+/** Platform ceilings. Workspace policy can only lower these values. */
+export const PLATFORM_CHANNEL_LIMITS = DEFAULT_AGENT_LIMITS;
+const Limits = Schema.Struct({
+    perSender: Schema.Struct({ turnsPerMinute: Schema.Int, turnsPerDay: Schema.Int }),
+    newUsersPerHour: Schema.Int,
+    workspaceTurnsPerDay: Schema.Int,
+});
+export function clampChannelLimits(input) {
+    const clamp = (value, ceiling) => Number.isSafeInteger(value) && value > 0 ? Math.min(value, ceiling) : ceiling;
+    return {
+        perSender: {
+            turnsPerMinute: clamp(input?.perSender?.turnsPerMinute, PLATFORM_CHANNEL_LIMITS.perSender.turnsPerMinute),
+            turnsPerDay: clamp(input?.perSender?.turnsPerDay, PLATFORM_CHANNEL_LIMITS.perSender.turnsPerDay),
+        },
+        newUsersPerHour: clamp(input?.newUsersPerHour, PLATFORM_CHANNEL_LIMITS.newUsersPerHour),
+        workspaceTurnsPerDay: clamp(input?.workspaceTurnsPerDay, PLATFORM_CHANNEL_LIMITS.workspaceTurnsPerDay),
+    };
+}
+/** Only trusted runtimes submit limits; channel-app callers omit them and reuse the latest policy. */
+export function effectiveChannelLimits(sql, input) {
+    return Effect.gen(function* () {
+        if (input !== undefined) {
+            const limits = clampChannelLimits(input);
+            yield* sql.unsafe(`INSERT INTO "${CHANNEL_LIMITS_TABLE}" ("id", "limits") VALUES (true, $1::jsonb)
+         ON CONFLICT ("id") DO UPDATE SET "limits" = EXCLUDED."limits"`, [JSON.stringify(limits)]);
+            return limits;
+        }
+        const [stored] = yield* sql.unsafe(`SELECT "limits" FROM "${CHANNEL_LIMITS_TABLE}" WHERE "id"`);
+        return stored === undefined
+            ? DEFAULT_AGENT_LIMITS
+            : clampChannelLimits(Schema.decodeUnknownSync(Limits)(stored.limits));
+    }).pipe(Effect.orDie);
+}
+const Counter = Schema.Struct({ count: Schema.Int, retry_after: Schema.Int });
+const decodeCounter = Schema.decodeUnknownSync(Counter);
+/** A failed send releases its claim; a lost process can be retried after a 30-second lease. */
+export function completeAgentLimitNotice(sql, input) {
+    const statement = input.delivered
+        ? `UPDATE "${AGENT_COUNTERS_TABLE}" SET "count" = 1, "notification_claimed_until" = NULL`
+        : `DELETE FROM "${AGENT_COUNTERS_TABLE}"`;
+    return sql
+        .unsafe(`${statement}
+     WHERE "notification_claim" = $1::uuid AND "count" = 0 RETURNING "key"`, [input.notificationId])
+        .pipe(Effect.map((updated) => updated.length > 0), Effect.orDie);
+}
+/** Count attempts durably; notify once per effective threshold within each fixed window. */
+export function countAgentAttempt(sql, input) {
+    return Effect.gen(function* () {
+        const [stored] = yield* sql.unsafe(`INSERT INTO "${AGENT_COUNTERS_TABLE}" ("key", "window_start", "count")
+       VALUES ($1, date_trunc($2, now()), 1)
+       ON CONFLICT ("key", "window_start") DO UPDATE
+       SET "count" = "${AGENT_COUNTERS_TABLE}"."count" + 1
+       RETURNING "count", ceil(extract(epoch FROM
+         "window_start" + ('1 ' || $2)::interval - now()))::int AS "retry_after"`, [`${input.scope}:${input.subject}`, input.window]);
+        if (stored === undefined) {
+            return yield* Effect.die(new Error("Agent counter did not return its count."));
+        }
+        const counter = decodeCounter(stored);
+        if (counter.count === 1) {
+            // Bound maintenance work under admission locks and leave busy windows to another request.
+            yield* sql.unsafe(`DELETE FROM "${AGENT_COUNTERS_TABLE}"
+         WHERE ctid IN (
+           SELECT ctid FROM "${AGENT_COUNTERS_TABLE}"
+           WHERE "window_start" < date_trunc('day', now()) - interval '1 day'
+           LIMIT 100
+           FOR UPDATE SKIP LOCKED
+         )`);
+        }
+        if (counter.count <= input.limit) {
+            return undefined;
+        }
+        const [claimed] = yield* sql.unsafe(`INSERT INTO "${AGENT_COUNTERS_TABLE}"
+         ("key", "window_start", "count", "notification_claim", "notification_claimed_until")
+       VALUES ($1, date_trunc($2, now()), 0, $3::uuid, now() + interval '30 seconds')
+       ON CONFLICT ("key", "window_start") DO UPDATE
+       SET "notification_claim" = EXCLUDED."notification_claim",
+           "notification_claimed_until" = EXCLUDED."notification_claimed_until"
+       WHERE "${AGENT_COUNTERS_TABLE}"."count" = 0
+         AND "${AGENT_COUNTERS_TABLE}"."notification_claimed_until" <= now()
+       RETURNING "notification_claim"`, [`notify:${input.scope}:${input.subject}:${input.limit}`, input.window, randomUUID()]);
+        return {
+            status: "limited",
+            scope: input.scope,
+            retryAfterSeconds: Math.max(1, counter.retry_after),
+            notify: claimed !== undefined,
+            ...(claimed === undefined ? {} : { notificationId: claimed.notification_claim }),
+        };
+    }).pipe(Effect.orDie);
+}

package/dist/runtime/agent-tasks.d.ts

@@ -0,0 +1,63 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import type { AgentTaskResult } from "../agent-task-contract.js";
+/** A task's status: `pending` and `started` are live until the deadline; the others are terminal. */
+export type AgentTaskStatus = "pending" | "started" | AgentTaskResult["status"];
+/** One row of `_agent_tasks`, as the service reads it. Its secret's hash is never read back. */
+export interface AgentTaskRecord {
+    readonly id: string;
+    /** The workflow's wire name, whose user the task acts as. */
+    readonly workflow: string;
+    readonly runId: string;
+    readonly hookToken: string;
+    readonly prompt: string;
+    readonly status: AgentTaskStatus;
+    /** The terminal outcome; `undefined` while the task is live. */
+    readonly result: AgentTaskResult | undefined;
+    readonly deadlineAt: Date;
+}
+/** How long tasks are kept after their deadline, for diagnosis, before the next start deletes them. */
+export declare const AGENT_TASK_RETENTION_DAYS = 30;
+/** The task store: the ontology database's `_agent_tasks`, which the service reads and changes. */
+export interface AgentTaskStore {
+    /** The task an `agentTask` call recorded under its hook token. */
+    readonly byHook: (hookToken: string) => Effect.Effect<AgentTaskRecord | undefined>;
+    /** The live task whose secret has this SHA-256: not terminal, and its deadline not passed. */
+    readonly live: (secretSha256: string) => Effect.Effect<AgentTaskRecord | undefined>;
+    /**
+     * Records a pending task, due `timeoutMs` from now on the database's clock, unless `limit` tasks
+     * are live: then `busy`, and nothing is written. A task the hook token already names is returned
+     * as it is. Tasks whose deadline passed {@link AGENT_TASK_RETENTION_DAYS} days ago are deleted.
+     */
+    readonly create: (input: {
+        readonly hookToken: string;
+        readonly workflow: string;
+        readonly runId: string;
+        readonly prompt: string;
+        readonly timeoutMs: number;
+        readonly secretSha256: string;
+        readonly limit: number;
+    }) => Effect.Effect<{
+        readonly status: "created";
+        readonly task: AgentTaskRecord;
+    } | {
+        readonly status: "existing";
+        readonly task: AgentTaskRecord;
+    } | {
+        readonly status: "busy";
+    }>;
+    /** Replaces the secret of a pending task; `false` when it is no longer pending. */
+    readonly rekey: (id: string, secretSha256: string) => Effect.Effect<boolean>;
+    /** Marks a pending task started; `false` when it is no longer pending. */
+    readonly markStarted: (id: string) => Effect.Effect<boolean>;
+    /**
+     * Makes a task that is not terminal end with `result`. The first outcome wins: `finished` is
+     * `false` when the task was already terminal, and `task` is the row after the attempt.
+     */
+    readonly finish: (id: string, result: AgentTaskResult) => Effect.Effect<{
+        readonly finished: boolean;
+        readonly task: AgentTaskRecord | undefined;
+    }>;
+}
+/** The task store over `_agent_tasks`. Database failures are defects. */
+export declare function sqlAgentTaskStore(sql: SqlClient.SqlClient): AgentTaskStore;