@authorbot/domain 0.1.0

package/dist/git-operation-state.d.ts

@@ -0,0 +1,44 @@
+import { type Denied } from "./decision.js";
+/**
+ * Git operation state machine (design section 20.2, Phase 2 contract
+ * section 5): `queued -> preparing -> committing -> committed -> verified`,
+ * failures -> `conflict | failed`, with bounded retries (3).
+ */
+export declare const GIT_OPERATION_STATES: readonly ["queued", "preparing", "committing", "committed", "verified", "conflict", "failed"];
+export type GitOperationState = (typeof GIT_OPERATION_STATES)[number];
+/** Maximum commit attempts per operation (contract section 5: bounded retries, 3). */
+export declare const MAX_GIT_ATTEMPTS = 3;
+/**
+ * Legal transitions. `conflict -> queued` is the (bounded) retry edge;
+ * `preparing`/`committing` may fail into `conflict` (stale expected head,
+ * non-fast-forward) or `failed` (non-retryable error, retries exhausted).
+ */
+export declare const GIT_OPERATION_TRANSITIONS: Readonly<Record<GitOperationState, readonly GitOperationState[]>>;
+export declare function canTransitionGitOperation(from: GitOperationState, to: GitOperationState): boolean;
+/**
+ * Attempt-accounted snapshot of an operation. `attempts` counts how many
+ * times the operation has entered `preparing` (i.e. commit attempts begun).
+ * A fresh operation starts `{ state: "queued", attempts: 0 }`.
+ */
+export interface GitOperationProgress {
+    readonly state: GitOperationState;
+    readonly attempts: number;
+}
+export declare const INITIAL_GIT_OPERATION: GitOperationProgress;
+export type GitOperationDenialReason = "illegal-transition" | "retries-exhausted";
+export type GitOperationTransitionResult = {
+    readonly allowed: true;
+    readonly next: GitOperationProgress;
+} | Denied<GitOperationDenialReason>;
+/**
+ * Apply a state change with bounded-retry accounting:
+ * - `queued -> preparing` increments `attempts` (an attempt begins).
+ * - `conflict -> queued` (retry) is denied with `retries-exhausted` once
+ *   `attempts >= maxAttempts`; the only legal exit is then `failed`.
+ */
+export declare function transitionGitOperation(current: GitOperationProgress, to: GitOperationState, maxAttempts?: number): GitOperationTransitionResult;
+/** Whether a conflicted operation may still be retried under the bound. */
+export declare function canRetryGitOperation(current: GitOperationProgress, maxAttempts?: number): boolean;
+/** Terminal states: no outgoing transitions remain. */
+export declare function isGitOperationTerminal(state: GitOperationState): boolean;
+//# sourceMappingURL=git-operation-state.d.ts.map

package/dist/git-operation-state.js

@@ -0,0 +1,65 @@
+import { denied } from "./decision.js";
+/**
+ * Git operation state machine (design section 20.2, Phase 2 contract
+ * section 5): `queued -> preparing -> committing -> committed -> verified`,
+ * failures -> `conflict | failed`, with bounded retries (3).
+ */
+export const GIT_OPERATION_STATES = [
+    "queued",
+    "preparing",
+    "committing",
+    "committed",
+    "verified",
+    "conflict",
+    "failed",
+];
+/** Maximum commit attempts per operation (contract section 5: bounded retries, 3). */
+export const MAX_GIT_ATTEMPTS = 3;
+/**
+ * Legal transitions. `conflict -> queued` is the (bounded) retry edge;
+ * `preparing`/`committing` may fail into `conflict` (stale expected head,
+ * non-fast-forward) or `failed` (non-retryable error, retries exhausted).
+ */
+export const GIT_OPERATION_TRANSITIONS = Object.freeze({
+    queued: ["preparing"],
+    preparing: ["committing", "conflict", "failed"],
+    committing: ["committed", "conflict", "failed"],
+    committed: ["verified"],
+    verified: [],
+    conflict: ["queued", "failed"],
+    failed: [],
+});
+export function canTransitionGitOperation(from, to) {
+    return GIT_OPERATION_TRANSITIONS[from].includes(to);
+}
+export const INITIAL_GIT_OPERATION = Object.freeze({
+    state: "queued",
+    attempts: 0,
+});
+/**
+ * Apply a state change with bounded-retry accounting:
+ * - `queued -> preparing` increments `attempts` (an attempt begins).
+ * - `conflict -> queued` (retry) is denied with `retries-exhausted` once
+ *   `attempts >= maxAttempts`; the only legal exit is then `failed`.
+ */
+export function transitionGitOperation(current, to, maxAttempts = MAX_GIT_ATTEMPTS) {
+    if (!canTransitionGitOperation(current.state, to)) {
+        return denied("illegal-transition", `git operation cannot change from "${current.state}" to "${to}"`);
+    }
+    if (current.state === "conflict" && to === "queued" && current.attempts >= maxAttempts) {
+        return denied("retries-exhausted", `git operation already used ${current.attempts} of ${maxAttempts} attempts; it must fail`);
+    }
+    const attempts = current.state === "queued" && to === "preparing"
+        ? current.attempts + 1
+        : current.attempts;
+    return { allowed: true, next: { state: to, attempts } };
+}
+/** Whether a conflicted operation may still be retried under the bound. */
+export function canRetryGitOperation(current, maxAttempts = MAX_GIT_ATTEMPTS) {
+    return current.state === "conflict" && current.attempts < maxAttempts;
+}
+/** Terminal states: no outgoing transitions remain. */
+export function isGitOperationTerminal(state) {
+    return GIT_OPERATION_TRANSITIONS[state].length === 0;
+}
+//# sourceMappingURL=git-operation-state.js.map

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export { ALLOWED, denied } from "./decision.js";
+export { ANNOTATION_POLICIES, DEFAULT_ANNOTATION_POLICY, checkAnnotationPolicy, isAnnotationPolicy, policyRequiresApproval, } from "./annotation-policy.js";
+export type { AnnotationPolicy, AnnotationPolicyDenialReason, AnnotationPolicyRequest, PolicyCapability, } from "./annotation-policy.js";
+export type { Allowed, Decision, Denied } from "./decision.js";
+export { ROLES, ROLE_SCOPES, SCOPES, effectiveScopes, requireScope, requireScopes, roleSchema, roleScopes, scopeSchema, } from "./scopes.js";
+export type { Role, Scope, ScopeDenialReason } from "./scopes.js";
+export { ANNOTATION_STATUSES, ANNOTATION_TRANSITIONS, authorizeAnnotationWithdraw, canTransitionAnnotation, transitionAnnotation, } from "./annotation-state.js";
+export type { AnnotationStatus, AnnotationTransitionDenialReason, WithdrawDenialReason, } from "./annotation-state.js";
+export { GIT_OPERATION_STATES, GIT_OPERATION_TRANSITIONS, INITIAL_GIT_OPERATION, MAX_GIT_ATTEMPTS, canRetryGitOperation, canTransitionGitOperation, isGitOperationTerminal, transitionGitOperation, } from "./git-operation-state.js";
+export type { GitOperationDenialReason, GitOperationProgress, GitOperationState, GitOperationTransitionResult, } from "./git-operation-state.js";
+export { MAX_BODY_BYTES, MAX_TOKEN_NAME_LENGTH, bodySchema, normalizeBody, createAnnotationCommandSchema, createReplyCommandSchema, mintAgentTokenCommandSchema, orderedRangeTargetSchema, utf8ByteLength, withdrawAnnotationCommandSchema, } from "./commands.js";
+export type { CreateAnnotationCommand, CreateReplyCommand, MintAgentTokenCommand, MintAgentTokenCommandInput, WithdrawAnnotationCommand, } from "./commands.js";
+export { VOTE_VALUES, authorizeVote, castVoteCommandSchema, clearVoteCommandSchema, voteValueSchema, } from "./vote.js";
+export type { CastVoteCommand, ClearVoteCommand, VoteDenialReason, VoteValue } from "./vote.js";
+export { DECISION_RESULTS, DECISION_SUPPORT_CHANGED_EVENT, decisionResultSchema, resolveSupportChange, } from "./decision-support.js";
+export type { DecisionResult, SupportChangeOutcome, SupportChangeTransition, } from "./decision-support.js";
+export { PHASE3_WORK_ITEM_STATUSES, WORK_ITEM_STATUSES, WORK_ITEM_TRANSITIONS, canTransitionWorkItem, isPhase3WorkItemStatus, transitionWorkItem, } from "./work-item-state.js";
+export type { WorkItemStatus, WorkItemTransitionDenialReason, } from "./work-item-state.js";
+export { FORCE_CREATE_RULE_VERSION, MAX_OVERRIDE_REASON_LENGTH, MIN_OVERRIDE_REASON_LENGTH, authorizeCancelWorkItem, authorizeForceCreateWorkItem, authorizeRejectSuggestion, authorizeReopenSuggestion, cancelWorkItemCommandSchema, forceCreateWorkItemCommandSchema, overrideReasonSchema, rejectSuggestionCommandSchema, reopenSuggestionCommandSchema, } from "./overrides.js";
+export type { CancelWorkItemCommand, ForceCreateWorkItemCommand, RejectSuggestionCommand, ReopenSuggestionCommand, SuggestionOverrideDenialReason, WorkItemOverrideDenialReason, } from "./overrides.js";
+export { AGENT_TOKEN_PREFIX, AGENT_TOKEN_REGEX, AGENT_TOKEN_SECRET_LENGTH, DEFAULT_TOKEN_TTL_DAYS, LAST_USED_UPDATE_INTERVAL_MS, MAX_TOKEN_TTL_DAYS, SESSION_ID_LENGTH, SESSION_ID_REGEX, SESSION_TTL_DAYS, agentTokenSchema, checkTokenActive, isAgentTokenFormat, isSessionIdFormat, parseAgentToken, resolveSessionExpiry, resolveTokenExpiry, sessionIdSchema, shouldUpdateLastUsed, toTimestamp, } from "./token.js";
+export type { AgentTokenParseFailure, AgentTokenParseResult, TokenExpiryResult, TokenInactiveReason, } from "./token.js";
+export { DEFAULT_LEASE_CONFIG, LEASE_DURATION_MS, LEASE_MAX_TOTAL_DURATION_MS, LEASE_RENEWAL_DURATION_MS, LEASE_RENEWAL_PROMPT_BEFORE_MS, checkLeaseActive, checkLeaseRenewable, checkWorkItemClaimable, isLeaseExpired, leaseConfigSchema, parseIsoDuration, renewalPromptAt, resolveLeaseExpiry, shouldExpireLease, } from "./lease.js";
+export type { ClaimCheckResult, ClaimDenialReason, IsoDurationParseResult, LeaseConfig, LeaseConfigInput, LeaseInactiveReason, LeaseSnapshot, RenewCheckResult, RenewDenialReason, } from "./lease.js";
+export { LEASE_TOKEN_PREFIX, LEASE_TOKEN_REGEX, LEASE_TOKEN_SECRET_LENGTH, isLeaseTokenFormat, leaseTokenSchema, parseLeaseToken, } from "./lease-token.js";
+export type { LeaseTokenParseFailure, LeaseTokenParseResult, } from "./lease-token.js";
+export { PHASE4_WORK_ITEM_STATUSES, WORK_ITEM_TRIGGERS, WORK_ITEM_TRIGGER_EDGES, applyWorkItemTrigger, isWorkItemTerminal, transitionWorkItemPhase4, } from "./work-item-lifecycle.js";
+export type { WorkItemLifecycleDenialReason, WorkItemTrigger, WorkItemTriggerResult, } from "./work-item-lifecycle.js";
+export { CONTENT_HASH_REGEX, MAX_SUBMISSION_CONTENT_BYTES, SUBMISSION_SCHEMA_IDS, SUBMISSION_TYPES, WORK_ITEM_SUBMISSION_TYPES, checkSubmissionBase, checkSubmissionTypeMatches, contentHashSchema, requiredSubmissionType, submissionTypeSchema, submitWorkCommandSchema, } from "./submission.js";
+export type { SubmissionBaseDenialReason, SubmissionType, SubmissionTypeDenialReason, SubmitWorkCommand, } from "./submission.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,16 @@
+export { ALLOWED, denied } from "./decision.js";
+export { ANNOTATION_POLICIES, DEFAULT_ANNOTATION_POLICY, checkAnnotationPolicy, isAnnotationPolicy, policyRequiresApproval, } from "./annotation-policy.js";
+export { ROLES, ROLE_SCOPES, SCOPES, effectiveScopes, requireScope, requireScopes, roleSchema, roleScopes, scopeSchema, } from "./scopes.js";
+export { ANNOTATION_STATUSES, ANNOTATION_TRANSITIONS, authorizeAnnotationWithdraw, canTransitionAnnotation, transitionAnnotation, } from "./annotation-state.js";
+export { GIT_OPERATION_STATES, GIT_OPERATION_TRANSITIONS, INITIAL_GIT_OPERATION, MAX_GIT_ATTEMPTS, canRetryGitOperation, canTransitionGitOperation, isGitOperationTerminal, transitionGitOperation, } from "./git-operation-state.js";
+export { MAX_BODY_BYTES, MAX_TOKEN_NAME_LENGTH, bodySchema, normalizeBody, createAnnotationCommandSchema, createReplyCommandSchema, mintAgentTokenCommandSchema, orderedRangeTargetSchema, utf8ByteLength, withdrawAnnotationCommandSchema, } from "./commands.js";
+export { VOTE_VALUES, authorizeVote, castVoteCommandSchema, clearVoteCommandSchema, voteValueSchema, } from "./vote.js";
+export { DECISION_RESULTS, DECISION_SUPPORT_CHANGED_EVENT, decisionResultSchema, resolveSupportChange, } from "./decision-support.js";
+export { PHASE3_WORK_ITEM_STATUSES, WORK_ITEM_STATUSES, WORK_ITEM_TRANSITIONS, canTransitionWorkItem, isPhase3WorkItemStatus, transitionWorkItem, } from "./work-item-state.js";
+export { FORCE_CREATE_RULE_VERSION, MAX_OVERRIDE_REASON_LENGTH, MIN_OVERRIDE_REASON_LENGTH, authorizeCancelWorkItem, authorizeForceCreateWorkItem, authorizeRejectSuggestion, authorizeReopenSuggestion, cancelWorkItemCommandSchema, forceCreateWorkItemCommandSchema, overrideReasonSchema, rejectSuggestionCommandSchema, reopenSuggestionCommandSchema, } from "./overrides.js";
+export { AGENT_TOKEN_PREFIX, AGENT_TOKEN_REGEX, AGENT_TOKEN_SECRET_LENGTH, DEFAULT_TOKEN_TTL_DAYS, LAST_USED_UPDATE_INTERVAL_MS, MAX_TOKEN_TTL_DAYS, SESSION_ID_LENGTH, SESSION_ID_REGEX, SESSION_TTL_DAYS, agentTokenSchema, checkTokenActive, isAgentTokenFormat, isSessionIdFormat, parseAgentToken, resolveSessionExpiry, resolveTokenExpiry, sessionIdSchema, shouldUpdateLastUsed, toTimestamp, } from "./token.js";
+export { DEFAULT_LEASE_CONFIG, LEASE_DURATION_MS, LEASE_MAX_TOTAL_DURATION_MS, LEASE_RENEWAL_DURATION_MS, LEASE_RENEWAL_PROMPT_BEFORE_MS, checkLeaseActive, checkLeaseRenewable, checkWorkItemClaimable, isLeaseExpired, leaseConfigSchema, parseIsoDuration, renewalPromptAt, resolveLeaseExpiry, shouldExpireLease, } from "./lease.js";
+export { LEASE_TOKEN_PREFIX, LEASE_TOKEN_REGEX, LEASE_TOKEN_SECRET_LENGTH, isLeaseTokenFormat, leaseTokenSchema, parseLeaseToken, } from "./lease-token.js";
+export { PHASE4_WORK_ITEM_STATUSES, WORK_ITEM_TRIGGERS, WORK_ITEM_TRIGGER_EDGES, applyWorkItemTrigger, isWorkItemTerminal, transitionWorkItemPhase4, } from "./work-item-lifecycle.js";
+export { CONTENT_HASH_REGEX, MAX_SUBMISSION_CONTENT_BYTES, SUBMISSION_SCHEMA_IDS, SUBMISSION_TYPES, WORK_ITEM_SUBMISSION_TYPES, checkSubmissionBase, checkSubmissionTypeMatches, contentHashSchema, requiredSubmissionType, submissionTypeSchema, submitWorkCommandSchema, } from "./submission.js";
+//# sourceMappingURL=index.js.map

package/dist/lease-token.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+/**
+ * Lease-token FORMAT helpers only (Phase 4 contract section 2): parse and
+ * shape-check, no crypto. Generating the 256-bit random secret, hashing it
+ * (SHA-256), storing only the hash, and the constant-time compare are the
+ * API layer's job — exactly the split used for agent tokens in `token.ts`.
+ * Failure results carry a reason only and never echo any part of the value;
+ * lease tokens are never logged.
+ *
+ * Format (resolved ambiguity — the contracts pin "opaque 256-bit token" but
+ * no encoding): `authorbot_lease_` + 43 base64url chars, matching the agent
+ * token secret encoding. The distinct prefix makes a leaked lease token
+ * identifiable and unconfusable with an agent credential (an agent token is
+ * `authorbot_` + exactly 43 chars, so the two spaces are disjoint).
+ */
+export declare const LEASE_TOKEN_PREFIX = "authorbot_lease_";
+export declare const LEASE_TOKEN_SECRET_LENGTH = 43;
+export declare const LEASE_TOKEN_REGEX: RegExp;
+export declare const leaseTokenSchema: z.ZodString;
+export declare function isLeaseTokenFormat(value: string): boolean;
+export type LeaseTokenParseFailure = "bad-prefix" | "bad-length" | "bad-charset";
+export type LeaseTokenParseResult = {
+    readonly ok: true;
+    readonly secret: string;
+} | {
+    readonly ok: false;
+    readonly reason: LeaseTokenParseFailure;
+};
+/**
+ * Shape-check a presented lease token and split off the secret part (which
+ * the API layer hashes for the constant-time comparison against the stored
+ * hash). Failures never contain any fragment of the presented value.
+ */
+export declare function parseLeaseToken(value: string): LeaseTokenParseResult;
+//# sourceMappingURL=lease-token.d.ts.map

package/dist/lease-token.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+/**
+ * Lease-token FORMAT helpers only (Phase 4 contract section 2): parse and
+ * shape-check, no crypto. Generating the 256-bit random secret, hashing it
+ * (SHA-256), storing only the hash, and the constant-time compare are the
+ * API layer's job — exactly the split used for agent tokens in `token.ts`.
+ * Failure results carry a reason only and never echo any part of the value;
+ * lease tokens are never logged.
+ *
+ * Format (resolved ambiguity — the contracts pin "opaque 256-bit token" but
+ * no encoding): `authorbot_lease_` + 43 base64url chars, matching the agent
+ * token secret encoding. The distinct prefix makes a leaked lease token
+ * identifiable and unconfusable with an agent credential (an agent token is
+ * `authorbot_` + exactly 43 chars, so the two spaces are disjoint).
+ */
+export const LEASE_TOKEN_PREFIX = "authorbot_lease_";
+export const LEASE_TOKEN_SECRET_LENGTH = 43;
+const BASE64URL_CHAR = /^[A-Za-z0-9_-]+$/;
+export const LEASE_TOKEN_REGEX = /^authorbot_lease_[A-Za-z0-9_-]{43}$/;
+export const leaseTokenSchema = z
+    .string()
+    .regex(LEASE_TOKEN_REGEX, "must be 'authorbot_lease_' followed by 43 base64url characters");
+export function isLeaseTokenFormat(value) {
+    return LEASE_TOKEN_REGEX.test(value);
+}
+/**
+ * Shape-check a presented lease token and split off the secret part (which
+ * the API layer hashes for the constant-time comparison against the stored
+ * hash). Failures never contain any fragment of the presented value.
+ */
+export function parseLeaseToken(value) {
+    if (!value.startsWith(LEASE_TOKEN_PREFIX)) {
+        return { ok: false, reason: "bad-prefix" };
+    }
+    const secret = value.slice(LEASE_TOKEN_PREFIX.length);
+    if (secret.length !== LEASE_TOKEN_SECRET_LENGTH) {
+        return { ok: false, reason: "bad-length" };
+    }
+    if (!BASE64URL_CHAR.test(secret)) {
+        return { ok: false, reason: "bad-charset" };
+    }
+    return { ok: true, secret };
+}
+//# sourceMappingURL=lease-token.js.map

package/dist/lease.d.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { type WorkItemStatus } from "@authorbot/schemas";
+import { type Decision, type Denied } from "./decision.js";
+/** Design section 25 defaults: duration PT30M. */
+export declare const LEASE_DURATION_MS: number;
+/** Design section 25 defaults: renewal_duration PT30M. */
+export declare const LEASE_RENEWAL_DURATION_MS: number;
+/** Design section 25 defaults: maximum_total_duration PT4H. */
+export declare const LEASE_MAX_TOTAL_DURATION_MS: number;
+/** Design section 25 defaults: renewal_prompt_before PT5M (UI concern). */
+export declare const LEASE_RENEWAL_PROMPT_BEFORE_MS: number;
+export type IsoDurationParseResult = {
+    readonly ok: true;
+    readonly ms: number;
+} | {
+    readonly ok: false;
+    readonly reason: "bad-format" | "zero-duration";
+};
+/**
+ * Parse the ISO-8601 duration subset the contracts use (`PT30M`, `PT4H`,
+ * `P1D`, combinations with integer designators; no years/months/weeks —
+ * calendar units are ambiguous in milliseconds). Used to validate `LEASE_*`
+ * env overrides at boot (Phase 4 contract section 2).
+ */
+export declare function parseIsoDuration(value: string): IsoDurationParseResult;
+/**
+ * Lease timing configuration in milliseconds, with design section 25
+ * defaults. Boot-time validation of env overrides (contract section 2):
+ * every duration positive, renewal prompt strictly inside the duration, and
+ * the initial duration within the max total (otherwise a lease would be born
+ * beyond its own cap).
+ */
+export declare const leaseConfigSchema: z.ZodObject<{
+    durationMs: z.ZodDefault<z.ZodNumber>;
+    renewalDurationMs: z.ZodDefault<z.ZodNumber>;
+    maxTotalDurationMs: z.ZodDefault<z.ZodNumber>;
+    renewalPromptBeforeMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type LeaseConfig = z.infer<typeof leaseConfigSchema>;
+export type LeaseConfigInput = z.input<typeof leaseConfigSchema>;
+/** The design section 25 defaults as a parsed config. */
+export declare const DEFAULT_LEASE_CONFIG: LeaseConfig;
+/**
+ * The clock-relevant columns of a `leases` row (contract section 2). The
+ * token hash deliberately does not appear: comparing presented tokens is the
+ * API layer's constant-time job.
+ */
+export interface LeaseSnapshot {
+    readonly expiresAt: string;
+    readonly maxExpiresAt: string;
+    readonly releasedAt?: string | null;
+    readonly revokedAt?: string | null;
+}
+/** Timestamps for a freshly issued lease (claim step; design section 12.2). */
+export declare function resolveLeaseExpiry(now: Date, config?: LeaseConfig): {
+    expiresAt: string;
+    maxExpiresAt: string;
+};
+/**
+ * Expiry is inclusive at exactly `expires_at` (matching `checkTokenActive`):
+ * no submission is accepted merely because a countdown still shows 0:00.
+ */
+export declare function isLeaseExpired(lease: LeaseSnapshot, now: Date): boolean;
+export type LeaseInactiveReason = "expired" | "released" | "revoked";
+/**
+ * Whether a lease still backs commands at `now`. Check order follows the
+ * contract section 4 verification order ("not expired / not released"):
+ * expired first, then released, then revoked. Used by renew, release, and
+ * submission checks alike — an expired, released, or revoked lease can do
+ * nothing further (contract section 2: renewing an expired lease is a 409).
+ */
+export declare function checkLeaseActive(lease: LeaseSnapshot, now: Date): Decision<LeaseInactiveReason>;
+export type ClaimDenialReason = "not-claimable" | "lease-held";
+export type ClaimCheckResult = {
+    readonly allowed: true;
+    /**
+     * True when the item is still `leased` but its lease is no longer
+     * active: the claim command must expire the stale lease in the same
+     * serialized batch before issuing the new one (contract section 2).
+     */
+    readonly priorLeaseExpired: boolean;
+} | Denied<ClaimDenialReason>;
+/**
+ * Claimability (design section 12.2 step 1, contract section 2): the item is
+ * `ready`, or it is `leased` and no LIVE lease occupies its slot. Only a
+ * `leased` item whose recorded active lease is still live denies with
+ * `lease-held` (the 409 the losing claimant sees; holder-safe messaging is
+ * the API's concern). Scope (`work:claim`) and per-type capability checks are
+ * separate (`requireScope`, `requiredSubmissionType`).
+ *
+ * A `leased` item with NO active lease row at all is claimable, not held: the
+ * slot is provably free (the unique index admits exactly one active lease, so
+ * "none" is unambiguous). That combination is what an interrupted expiry or a
+ * bare administrative revocation leaves behind, and treating it as
+ * `lease-held` made such items permanently unclaimable, unreleasable, and
+ * unsweepable — recoverable only by direct database surgery. Claiming
+ * self-heals it instead: `priorLeaseExpired` sends the caller down the
+ * expire-then-claim path, whose compare-and-swap starts from `leased`.
+ */
+export declare function checkWorkItemClaimable(status: WorkItemStatus, activeLease: LeaseSnapshot | null, now: Date): ClaimCheckResult;
+export type RenewDenialReason = LeaseInactiveReason | "max-total-exceeded";
+export type RenewCheckResult = {
+    readonly allowed: true;
+    readonly expiresAt: string;
+} | Denied<RenewDenialReason>;
+/**
+ * Renewal (design section 12.3, contract section 2): only an active lease
+ * renews; the new expiry is the current `expires_at` plus the renewal
+ * duration ("extends by"), clamped to `max_expires_at`. When the lease
+ * already sits at its max-total cap so no extension is possible, the renewal
+ * is rejected with `max-total-exceeded` rather than succeeding as a no-op —
+ * a partially clamped extension is still allowed. Verifying the presented
+ * token against the stored hash happens before this in the API layer.
+ */
+export declare function checkLeaseRenewable(lease: LeaseSnapshot, now: Date, config?: LeaseConfig): RenewCheckResult;
+/**
+ * When the UI should prompt for renewal (design section 12.3: five minutes
+ * before expiration). Purely advisory; expiry itself never depends on it.
+ */
+export declare function renewalPromptAt(lease: LeaseSnapshot, config?: LeaseConfig): string;
+/**
+ * Whether a sweep (`sweepExpiredLeases`) or lazy check should expire this
+ * lease now: it is past `expires_at` and has not already been ended some
+ * other way (released/revoked leases were already dealt with).
+ */
+export declare function shouldExpireLease(lease: LeaseSnapshot, now: Date): boolean;
+//# sourceMappingURL=lease.d.ts.map

package/dist/lease.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import {} from "@authorbot/schemas";
+import { ALLOWED, denied } from "./decision.js";
+import { toTimestamp } from "./token.js";
+/**
+ * Lease VALUE rules (Phase 4 contract section 2, design sections 12, 25).
+ * Pure logic only: claimability, renewability under the max-total cap, and
+ * expiry given an injected clock. Token generation, SHA-256 hashing, and the
+ * constant-time compare are the API layer's job (as with agent tokens); the
+ * serialized compare-and-set that makes two simultaneous claims produce
+ * exactly one success is the database's job. Nothing here ever logs or
+ * embeds a lease token.
+ */
+const MS_PER_SECOND = 1000;
+const MS_PER_MINUTE = 60 * MS_PER_SECOND;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+/** Design section 25 defaults: duration PT30M. */
+export const LEASE_DURATION_MS = 30 * MS_PER_MINUTE;
+/** Design section 25 defaults: renewal_duration PT30M. */
+export const LEASE_RENEWAL_DURATION_MS = 30 * MS_PER_MINUTE;
+/** Design section 25 defaults: maximum_total_duration PT4H. */
+export const LEASE_MAX_TOTAL_DURATION_MS = 4 * MS_PER_HOUR;
+/** Design section 25 defaults: renewal_prompt_before PT5M (UI concern). */
+export const LEASE_RENEWAL_PROMPT_BEFORE_MS = 5 * MS_PER_MINUTE;
+const ISO_DURATION_REGEX = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;
+/**
+ * Parse the ISO-8601 duration subset the contracts use (`PT30M`, `PT4H`,
+ * `P1D`, combinations with integer designators; no years/months/weeks —
+ * calendar units are ambiguous in milliseconds). Used to validate `LEASE_*`
+ * env overrides at boot (Phase 4 contract section 2).
+ */
+export function parseIsoDuration(value) {
+    const match = ISO_DURATION_REGEX.exec(value);
+    if (match === null) {
+        return { ok: false, reason: "bad-format" };
+    }
+    const [, days, hours, minutes, seconds] = match;
+    if (days === undefined &&
+        hours === undefined &&
+        minutes === undefined &&
+        seconds === undefined) {
+        return { ok: false, reason: "bad-format" };
+    }
+    const ms = Number(days ?? 0) * MS_PER_DAY +
+        Number(hours ?? 0) * MS_PER_HOUR +
+        Number(minutes ?? 0) * MS_PER_MINUTE +
+        Number(seconds ?? 0) * MS_PER_SECOND;
+    if (ms === 0) {
+        return { ok: false, reason: "zero-duration" };
+    }
+    return { ok: true, ms };
+}
+/**
+ * Lease timing configuration in milliseconds, with design section 25
+ * defaults. Boot-time validation of env overrides (contract section 2):
+ * every duration positive, renewal prompt strictly inside the duration, and
+ * the initial duration within the max total (otherwise a lease would be born
+ * beyond its own cap).
+ */
+export const leaseConfigSchema = z
+    .strictObject({
+    durationMs: z.number().int().positive().default(LEASE_DURATION_MS),
+    renewalDurationMs: z.number().int().positive().default(LEASE_RENEWAL_DURATION_MS),
+    maxTotalDurationMs: z.number().int().positive().default(LEASE_MAX_TOTAL_DURATION_MS),
+    renewalPromptBeforeMs: z
+        .number()
+        .int()
+        .positive()
+        .default(LEASE_RENEWAL_PROMPT_BEFORE_MS),
+})
+    .refine((config) => config.renewalPromptBeforeMs < config.durationMs, {
+    path: ["renewalPromptBeforeMs"],
+    message: "renewal prompt must fire strictly before the lease duration elapses",
+})
+    .refine((config) => config.durationMs <= config.maxTotalDurationMs, {
+    path: ["durationMs"],
+    message: "initial duration must not exceed the maximum total duration",
+});
+/** The design section 25 defaults as a parsed config. */
+export const DEFAULT_LEASE_CONFIG = Object.freeze(leaseConfigSchema.parse({}));
+/** Timestamps for a freshly issued lease (claim step; design section 12.2). */
+export function resolveLeaseExpiry(now, config = DEFAULT_LEASE_CONFIG) {
+    return {
+        expiresAt: toTimestamp(new Date(now.getTime() + config.durationMs)),
+        maxExpiresAt: toTimestamp(new Date(now.getTime() + config.maxTotalDurationMs)),
+    };
+}
+/**
+ * Expiry is inclusive at exactly `expires_at` (matching `checkTokenActive`):
+ * no submission is accepted merely because a countdown still shows 0:00.
+ */
+export function isLeaseExpired(lease, now) {
+    return now.getTime() >= Date.parse(lease.expiresAt);
+}
+/**
+ * Whether a lease still backs commands at `now`. Check order follows the
+ * contract section 4 verification order ("not expired / not released"):
+ * expired first, then released, then revoked. Used by renew, release, and
+ * submission checks alike — an expired, released, or revoked lease can do
+ * nothing further (contract section 2: renewing an expired lease is a 409).
+ */
+export function checkLeaseActive(lease, now) {
+    if (isLeaseExpired(lease, now)) {
+        return denied("expired", "lease has expired");
+    }
+    if (lease.releasedAt !== undefined && lease.releasedAt !== null) {
+        return denied("released", "lease has been released");
+    }
+    if (lease.revokedAt !== undefined && lease.revokedAt !== null) {
+        return denied("revoked", "lease has been revoked");
+    }
+    return ALLOWED;
+}
+/**
+ * Claimability (design section 12.2 step 1, contract section 2): the item is
+ * `ready`, or it is `leased` and no LIVE lease occupies its slot. Only a
+ * `leased` item whose recorded active lease is still live denies with
+ * `lease-held` (the 409 the losing claimant sees; holder-safe messaging is
+ * the API's concern). Scope (`work:claim`) and per-type capability checks are
+ * separate (`requireScope`, `requiredSubmissionType`).
+ *
+ * A `leased` item with NO active lease row at all is claimable, not held: the
+ * slot is provably free (the unique index admits exactly one active lease, so
+ * "none" is unambiguous). That combination is what an interrupted expiry or a
+ * bare administrative revocation leaves behind, and treating it as
+ * `lease-held` made such items permanently unclaimable, unreleasable, and
+ * unsweepable — recoverable only by direct database surgery. Claiming
+ * self-heals it instead: `priorLeaseExpired` sends the caller down the
+ * expire-then-claim path, whose compare-and-swap starts from `leased`.
+ */
+export function checkWorkItemClaimable(status, activeLease, now) {
+    if (status === "ready") {
+        return { allowed: true, priorLeaseExpired: false };
+    }
+    if (status !== "leased") {
+        return denied("not-claimable", `work item in status "${status}" cannot be claimed`);
+    }
+    if (activeLease !== null && checkLeaseActive(activeLease, now).allowed) {
+        return denied("lease-held", "work item is already leased");
+    }
+    return { allowed: true, priorLeaseExpired: true };
+}
+/**
+ * Renewal (design section 12.3, contract section 2): only an active lease
+ * renews; the new expiry is the current `expires_at` plus the renewal
+ * duration ("extends by"), clamped to `max_expires_at`. When the lease
+ * already sits at its max-total cap so no extension is possible, the renewal
+ * is rejected with `max-total-exceeded` rather than succeeding as a no-op —
+ * a partially clamped extension is still allowed. Verifying the presented
+ * token against the stored hash happens before this in the API layer.
+ */
+export function checkLeaseRenewable(lease, now, config = DEFAULT_LEASE_CONFIG) {
+    const active = checkLeaseActive(lease, now);
+    if (!active.allowed) {
+        return active;
+    }
+    const currentExpiry = Date.parse(lease.expiresAt);
+    const cap = Date.parse(lease.maxExpiresAt);
+    const extended = Math.min(currentExpiry + config.renewalDurationMs, cap);
+    if (extended <= currentExpiry) {
+        return denied("max-total-exceeded", "lease has reached its maximum total duration and cannot be renewed");
+    }
+    return { allowed: true, expiresAt: toTimestamp(new Date(extended)) };
+}
+/**
+ * When the UI should prompt for renewal (design section 12.3: five minutes
+ * before expiration). Purely advisory; expiry itself never depends on it.
+ */
+export function renewalPromptAt(lease, config = DEFAULT_LEASE_CONFIG) {
+    return toTimestamp(new Date(Date.parse(lease.expiresAt) - config.renewalPromptBeforeMs));
+}
+/**
+ * Whether a sweep (`sweepExpiredLeases`) or lazy check should expire this
+ * lease now: it is past `expires_at` and has not already been ended some
+ * other way (released/revoked leases were already dealt with).
+ */
+export function shouldExpireLease(lease, now) {
+    return (isLeaseExpired(lease, now) &&
+        (lease.releasedAt === undefined || lease.releasedAt === null) &&
+        (lease.revokedAt === undefined || lease.revokedAt === null));
+}
+//# sourceMappingURL=lease.js.map

package/dist/overrides.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { type AnnotationKind, type AnnotationStatus, type WorkItemStatus } from "@authorbot/schemas";
+import { type Decision } from "./decision.js";
+import type { Role } from "./scopes.js";
+/**
+ * Maintainer overrides (Phase 3 contract section 4; design section 11.2).
+ * All four are maintainer-only, require a recorded `reason`, and are recorded
+ * as decisions with `override_reason`. Force-create bypasses the rule but
+ * respects the same uniqueness key `(source_annotation_id, action_type,
+ * rule_version)` with `rule_version: 0`.
+ */
+/** Minimum meaningful override reason length (after trimming). */
+export declare const MIN_OVERRIDE_REASON_LENGTH = 3;
+/** Bound chosen for storage sanity (not contract-pinned). */
+export declare const MAX_OVERRIDE_REASON_LENGTH = 2000;
+export declare const overrideReasonSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/** `rule_version` recorded by force-created decisions (contract section 4). */
+export declare const FORCE_CREATE_RULE_VERSION = 0;
+/** Override 1: reject an open suggestion. */
+export declare const rejectSuggestionCommandSchema: z.ZodObject<{
+    annotationId: z.ZodString;
+    reason: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>;
+export type RejectSuggestionCommand = z.infer<typeof rejectSuggestionCommandSchema>;
+/** Override 2: cancel a `ready` work item. */
+export declare const cancelWorkItemCommandSchema: z.ZodObject<{
+    workItemId: z.ZodString;
+    reason: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>;
+export type CancelWorkItemCommand = z.infer<typeof cancelWorkItemCommandSchema>;
+/** Override 3: reopen a rejected suggestion. */
+export declare const reopenSuggestionCommandSchema: z.ZodObject<{
+    annotationId: z.ZodString;
+    reason: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>;
+export type ReopenSuggestionCommand = z.infer<typeof reopenSuggestionCommandSchema>;
+/**
+ * Override 4: force-create a work item bypassing the rule. `work_type` is not
+ * part of the command — it resolves from the annotation scope exactly as
+ * rule-created items do (Phase 3 contract section 3).
+ */
+export declare const forceCreateWorkItemCommandSchema: z.ZodObject<{
+    annotationId: z.ZodString;
+    reason: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>;
+export type ForceCreateWorkItemCommand = z.infer<typeof forceCreateWorkItemCommandSchema>;
+export type SuggestionOverrideDenialReason = "not-maintainer" | "not-a-suggestion" | "illegal-transition";
+/** Reject an open suggestion (`open -> rejected`). */
+export declare function authorizeRejectSuggestion(input: {
+    actorRole: Role;
+    annotationKind: AnnotationKind;
+    annotationStatus: AnnotationStatus;
+}): Decision<SuggestionOverrideDenialReason>;
+/** Reopen a rejected suggestion (`rejected -> open`). */
+export declare function authorizeReopenSuggestion(input: {
+    actorRole: Role;
+    annotationKind: AnnotationKind;
+    annotationStatus: AnnotationStatus;
+}): Decision<SuggestionOverrideDenialReason>;
+export type WorkItemOverrideDenialReason = "not-maintainer" | "illegal-transition" | "phase-not-enabled";
+/** Cancel a `ready` work item (contract section 4: cancel before integration). */
+export declare function authorizeCancelWorkItem(input: {
+    actorRole: Role;
+    workItemStatus: WorkItemStatus;
+}): Decision<WorkItemOverrideDenialReason>;
+/**
+ * Force-create a work item for an open suggestion, bypassing the rule. The
+ * annotation must still be able to make the `open -> work_item_created`
+ * transition; uniqueness (one item per annotation/action/rule-version) is the
+ * DB constraint's job.
+ */
+export declare function authorizeForceCreateWorkItem(input: {
+    actorRole: Role;
+    annotationKind: AnnotationKind;
+    annotationStatus: AnnotationStatus;
+}): Decision<SuggestionOverrideDenialReason>;
+//# sourceMappingURL=overrides.d.ts.map