@authorbot/domain 0.1.0

package/dist/vote.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { uuidv7Schema } from "@authorbot/schemas";
+import { ALLOWED, denied } from "./decision.js";
+/**
+ * Vote commands (Phase 3 contract section 2):
+ * `PUT /v1/projects/{p}/annotations/{id}/vote` with `{ value }`, `DELETE`
+ * clears. One current vote per actor is a DB uniqueness concern (upsert);
+ * this module pins the command shapes and the suggestion-only rule.
+ */
+/** Vote values (contract section 2; mirrors `authorbot.instance/v1` `votes.values`). */
+export const VOTE_VALUES = ["approve", "reject", "abstain"];
+export const voteValueSchema = z.enum(VOTE_VALUES);
+/** `PUT .../annotations/{annotationId}/vote` — route param + body merged. */
+export const castVoteCommandSchema = z.strictObject({
+    annotationId: uuidv7Schema,
+    value: voteValueSchema,
+});
+/** `DELETE .../annotations/{annotationId}/vote` — the command is the route param. */
+export const clearVoteCommandSchema = z.strictObject({
+    annotationId: uuidv7Schema,
+});
+/**
+ * Suggestion-only guard (contract section 2: votes on comments → 422). Votes
+ * stay legal after `open` — sticky decisions require tracking vote changes on
+ * `work_item_created` annotations (contract section 4) — so annotation status
+ * is deliberately not checked here; `votes:write` scope enforcement is the
+ * API layer's (`requireScope`).
+ */
+export function authorizeVote(input) {
+    if (input.annotationKind !== "suggestion") {
+        return denied("not-a-suggestion", "votes apply to suggestions only; comments cannot be voted on");
+    }
+    return ALLOWED;
+}
+//# sourceMappingURL=vote.js.map

package/dist/work-item-lifecycle.d.ts

@@ -0,0 +1,41 @@
+import { type WorkItemStatus } from "@authorbot/schemas";
+import { type Decision, type Denied } from "./decision.js";
+/**
+ * Phase 4 work-item lifecycle: the full design section 9.5 machine with the
+ * Phase 3 gate lifted (Phase 4 contract sections 2, 4, 5). The graph itself
+ * has been declared since Phase 3 (`WORK_ITEM_TRANSITIONS`); this module
+ * adds the executable, trigger-labelled form. `transitionWorkItem` (the
+ * Phase 3-gated function) is left untouched for compatibility — Phase 4
+ * call sites use `transitionWorkItemPhase4` / `applyWorkItemTrigger`.
+ */
+/**
+ * The design section 9.5 edge labels. One trigger per labelled arrow;
+ * `expire` and `release` are the two expiry/release back-edges sharing
+ * `leased -> ready`, and `cancel` covers both maintainer-action arrows.
+ */
+export declare const WORK_ITEM_TRIGGERS: readonly ["claim", "expire", "release", "submit", "validation_passed", "validation_failed", "apply_succeeded", "apply_conflicted", "conflict_resolution_prepared", "cancel"];
+export type WorkItemTrigger = (typeof WORK_ITEM_TRIGGERS)[number];
+/** Trigger -> the design edges it may traverse (exactly section 9.5). */
+export declare const WORK_ITEM_TRIGGER_EDGES: Readonly<Record<WorkItemTrigger, ReadonlyArray<readonly [WorkItemStatus, WorkItemStatus]>>>;
+/** Statuses with no outgoing edges (design section 9.5). */
+export declare function isWorkItemTerminal(status: WorkItemStatus): boolean;
+export type WorkItemLifecycleDenialReason = "illegal-transition";
+/**
+ * Phase 4 edge check: every design section 9.5 edge is executable, nothing
+ * else is. (Contrast `transitionWorkItem`, which additionally applies the
+ * Phase 3 gate.)
+ */
+export declare function transitionWorkItemPhase4(from: WorkItemStatus, to: WorkItemStatus): Decision<WorkItemLifecycleDenialReason>;
+export type WorkItemTriggerResult = {
+    readonly allowed: true;
+    readonly next: WorkItemStatus;
+} | Denied<WorkItemLifecycleDenialReason>;
+/**
+ * Apply a labelled trigger to a status. Deterministic: every trigger maps a
+ * given status to at most one next status, so commands can ask "what does
+ * `expire` do to this item?" without hand-picking the target state.
+ */
+export declare function applyWorkItemTrigger(status: WorkItemStatus, trigger: WorkItemTrigger): WorkItemTriggerResult;
+/** All statuses are live in Phase 4 (the Phase 3 stop-at-ready gate is lifted). */
+export declare const PHASE4_WORK_ITEM_STATUSES: readonly ["ready", "leased", "submitted", "applying", "completed", "conflict", "failed", "cancelled"];
+//# sourceMappingURL=work-item-lifecycle.d.ts.map

package/dist/work-item-lifecycle.js

@@ -0,0 +1,75 @@
+import { WORK_ITEM_STATUSES } from "@authorbot/schemas";
+import { ALLOWED, denied } from "./decision.js";
+import { WORK_ITEM_TRANSITIONS, canTransitionWorkItem } from "./work-item-state.js";
+/**
+ * Phase 4 work-item lifecycle: the full design section 9.5 machine with the
+ * Phase 3 gate lifted (Phase 4 contract sections 2, 4, 5). The graph itself
+ * has been declared since Phase 3 (`WORK_ITEM_TRANSITIONS`); this module
+ * adds the executable, trigger-labelled form. `transitionWorkItem` (the
+ * Phase 3-gated function) is left untouched for compatibility — Phase 4
+ * call sites use `transitionWorkItemPhase4` / `applyWorkItemTrigger`.
+ */
+/**
+ * The design section 9.5 edge labels. One trigger per labelled arrow;
+ * `expire` and `release` are the two expiry/release back-edges sharing
+ * `leased -> ready`, and `cancel` covers both maintainer-action arrows.
+ */
+export const WORK_ITEM_TRIGGERS = [
+    "claim",
+    "expire",
+    "release",
+    "submit",
+    "validation_passed",
+    "validation_failed",
+    "apply_succeeded",
+    "apply_conflicted",
+    "conflict_resolution_prepared",
+    "cancel",
+];
+/** Trigger -> the design edges it may traverse (exactly section 9.5). */
+export const WORK_ITEM_TRIGGER_EDGES = Object.freeze({
+    claim: [["ready", "leased"]],
+    expire: [["leased", "ready"]],
+    release: [["leased", "ready"]],
+    submit: [["leased", "submitted"]],
+    validation_passed: [["submitted", "applying"]],
+    validation_failed: [["submitted", "failed"]],
+    apply_succeeded: [["applying", "completed"]],
+    apply_conflicted: [["applying", "conflict"]],
+    conflict_resolution_prepared: [["conflict", "ready"]],
+    cancel: [
+        ["ready", "cancelled"],
+        ["leased", "cancelled"],
+    ],
+});
+/** Statuses with no outgoing edges (design section 9.5). */
+export function isWorkItemTerminal(status) {
+    return WORK_ITEM_TRANSITIONS[status].length === 0;
+}
+/**
+ * Phase 4 edge check: every design section 9.5 edge is executable, nothing
+ * else is. (Contrast `transitionWorkItem`, which additionally applies the
+ * Phase 3 gate.)
+ */
+export function transitionWorkItemPhase4(from, to) {
+    if (!canTransitionWorkItem(from, to)) {
+        return denied("illegal-transition", `work item status cannot change from "${from}" to "${to}"`);
+    }
+    return ALLOWED;
+}
+/**
+ * Apply a labelled trigger to a status. Deterministic: every trigger maps a
+ * given status to at most one next status, so commands can ask "what does
+ * `expire` do to this item?" without hand-picking the target state.
+ */
+export function applyWorkItemTrigger(status, trigger) {
+    for (const [from, to] of WORK_ITEM_TRIGGER_EDGES[trigger]) {
+        if (from === status) {
+            return { allowed: true, next: to };
+        }
+    }
+    return denied("illegal-transition", `trigger "${trigger}" does not apply to a work item in status "${status}"`);
+}
+/** All statuses are live in Phase 4 (the Phase 3 stop-at-ready gate is lifted). */
+export const PHASE4_WORK_ITEM_STATUSES = WORK_ITEM_STATUSES;
+//# sourceMappingURL=work-item-lifecycle.js.map

package/dist/work-item-state.d.ts

@@ -0,0 +1,28 @@
+import { WORK_ITEM_STATUSES, type WorkItemStatus } from "@authorbot/schemas";
+import { type Decision } from "./decision.js";
+export { WORK_ITEM_STATUSES };
+export type { WorkItemStatus };
+/**
+ * Work-item state machine (design section 9.5). The full transition graph is
+ * declared so Phase 4 is additive data, but Phase 3 stops at `ready` (Phase 3
+ * contract section 1: claims/leases/submissions are out of scope) — the only
+ * transition that may actually execute is `ready -> cancelled` (maintainer
+ * cancel). Every other graph edge is phase-gated: legal in the design, denied
+ * at runtime with `phase-not-enabled` until Phase 4 lifts the gate.
+ */
+export declare const WORK_ITEM_TRANSITIONS: Readonly<Record<WorkItemStatus, readonly WorkItemStatus[]>>;
+/** Statuses a work item can actually hold in Phase 3 (contract section 1). */
+export declare const PHASE3_WORK_ITEM_STATUSES: readonly ["ready", "cancelled"];
+export declare function isPhase3WorkItemStatus(status: WorkItemStatus): boolean;
+/** Whether the full design section 9.5 graph has this edge (phase-agnostic). */
+export declare function canTransitionWorkItem(from: WorkItemStatus, to: WorkItemStatus): boolean;
+export type WorkItemTransitionDenialReason = "illegal-transition" | "phase-not-enabled";
+/**
+ * Typed decision for a requested work-item status change under the Phase 3
+ * gate: the edge must exist in the design graph AND both endpoints must be
+ * Phase 3 statuses. Graph-legal but gated edges (e.g. `ready -> leased`)
+ * are denied with `phase-not-enabled` so callers can distinguish "never
+ * legal" from "not yet".
+ */
+export declare function transitionWorkItem(from: WorkItemStatus, to: WorkItemStatus): Decision<WorkItemTransitionDenialReason>;
+//# sourceMappingURL=work-item-state.d.ts.map

package/dist/work-item-state.js

@@ -0,0 +1,47 @@
+import { WORK_ITEM_STATUSES } from "@authorbot/schemas";
+import { ALLOWED, denied } from "./decision.js";
+export { WORK_ITEM_STATUSES };
+/**
+ * Work-item state machine (design section 9.5). The full transition graph is
+ * declared so Phase 4 is additive data, but Phase 3 stops at `ready` (Phase 3
+ * contract section 1: claims/leases/submissions are out of scope) — the only
+ * transition that may actually execute is `ready -> cancelled` (maintainer
+ * cancel). Every other graph edge is phase-gated: legal in the design, denied
+ * at runtime with `phase-not-enabled` until Phase 4 lifts the gate.
+ */
+export const WORK_ITEM_TRANSITIONS = Object.freeze({
+    ready: ["leased", "cancelled"],
+    leased: ["ready", "submitted", "cancelled"],
+    submitted: ["applying", "failed"],
+    applying: ["completed", "conflict"],
+    conflict: ["ready"],
+    completed: [],
+    failed: [],
+    cancelled: [],
+});
+/** Statuses a work item can actually hold in Phase 3 (contract section 1). */
+export const PHASE3_WORK_ITEM_STATUSES = ["ready", "cancelled"];
+export function isPhase3WorkItemStatus(status) {
+    return PHASE3_WORK_ITEM_STATUSES.includes(status);
+}
+/** Whether the full design section 9.5 graph has this edge (phase-agnostic). */
+export function canTransitionWorkItem(from, to) {
+    return WORK_ITEM_TRANSITIONS[from].includes(to);
+}
+/**
+ * Typed decision for a requested work-item status change under the Phase 3
+ * gate: the edge must exist in the design graph AND both endpoints must be
+ * Phase 3 statuses. Graph-legal but gated edges (e.g. `ready -> leased`)
+ * are denied with `phase-not-enabled` so callers can distinguish "never
+ * legal" from "not yet".
+ */
+export function transitionWorkItem(from, to) {
+    if (!canTransitionWorkItem(from, to)) {
+        return denied("illegal-transition", `work item status cannot change from "${from}" to "${to}"`);
+    }
+    if (!isPhase3WorkItemStatus(from) || !isPhase3WorkItemStatus(to)) {
+        return denied("phase-not-enabled", `work item transition "${from}" -> "${to}" is deferred to Phase 4 (work items stop at "ready" in Phase 3)`);
+    }
+    return ALLOWED;
+}
+//# sourceMappingURL=work-item-state.js.map

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@authorbot/domain",
+  "version": "0.1.0",
+  "description": "Pure domain logic for Authorbot: role/scope authorization, annotation and Git-operation state machines, command validators, and token/session value rules (Phase 2 contract section 3)",
+  "keywords": [
+    "authorbot",
+    "domain",
+    "authorization"
+  ],
+  "license": "MIT",
+  "author": "Joe Mattie",
+  "homepage": "https://github.com/JoeMattie/authorbot#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JoeMattie/authorbot.git",
+    "directory": "packages/domain"
+  },
+  "bugs": {
+    "url": "https://github.com/JoeMattie/authorbot/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "!dist/**/*.map"
+  ],
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@authorbot/schemas": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run --testTimeout=30000",
+    "typecheck": "tsc --noEmit"
+  }
+}