@authorbot/domain 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Mattie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/annotation-policy.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Annotation policy (Phase 7 contract "Restricting") — who may write to a
+ * book, and whether what they write appears immediately.
+ *
+ * | Mode                | Who may write            | Appears                    |
+ * |---------------------|--------------------------|----------------------------|
+ * | `open`              | any signed-in user       | immediately                |
+ * | `approval-gated`    | any signed-in user       | after a maintainer approves|
+ * | `collaborators-only`| members only             | immediately *(default)*    |
+ * | `locked`            | maintainers only         | immediately                |
+ *
+ * The rule is pure and lives here rather than in the API layer for the reason
+ * the contract gives for it existing at all: it is enforced SERVER-SIDE, "not
+ * merely reflected in the interface". A pure function with an exhaustive
+ * decision table is testable against every combination of mode, role, and
+ * credential kind without standing up a request, which is the only way to be
+ * confident that `locked` really does admit a maintainer's agent and really
+ * does refuse an editor.
+ *
+ * Two invariants hold across every mode and are asserted by the tests:
+ *
+ *   * **Anonymous writing is never available**, including under `open`.
+ *     Design §19.7 defers it until moderation, spam controls, privacy, and a
+ *     deletion policy all exist; Phase 7 supplies the first of the four.
+ *   * **An agent never inherits its owner's access.** An agent token writes
+ *     only through a membership of its own, which is the ordinary
+ *     scope-intersection rule of Phase 2 §3 and a deliberate grant. That is
+ *     also exactly how an author's agent keeps working under `locked`: it
+ *     holds a membership with the maintainer role, granted on purpose.
+ */
+import { type Decision } from "./decision.js";
+import type { Role } from "./scopes.js";
+export declare const ANNOTATION_POLICIES: readonly ["open", "approval-gated", "collaborators-only", "locked"];
+export type AnnotationPolicy = (typeof ANNOTATION_POLICIES)[number];
+/**
+ * The mode a book with no declared policy runs in: the Phase 2 behaviour,
+ * unchanged. A deployment upgrading into Phase 7 must not find its book
+ * suddenly writable by strangers, so the default is the restrictive end of the
+ * progression that people were already on — not the permissive end, and not
+ * `locked` either, which would lock out the collaborators they already have.
+ */
+export declare const DEFAULT_ANNOTATION_POLICY: AnnotationPolicy;
+export declare function isAnnotationPolicy(value: unknown): value is AnnotationPolicy;
+/** True when writes under this policy are queued for review rather than published. */
+export declare function policyRequiresApproval(policy: AnnotationPolicy): boolean;
+export type AnnotationPolicyDenialReason = 
+/** No credential at all. Refused in every mode, `open` included. */
+"anonymous"
+/** Signed in, but this mode admits only members of the project. */
+ | "members-only"
+/** The book is locked: maintainers only. */
+ | "locked"
+/**
+ * Signed in and not a member, asking for something a non-member could never
+ * do (voting, claiming, submitting) even in an open book — those are member
+ * capabilities, and `open` widens commenting, not the work queue.
+ */
+ | "member-capability";
+/**
+ * The write capabilities the policy arbitrates.
+ *
+ * `annotate` is the one the policy table is actually about — commenting and
+ * suggesting. The other three are member capabilities that `open` and
+ * `approval-gated` do NOT widen to strangers: a book that welcomes comments
+ * from the internet is not thereby handing the internet its governance votes
+ * or its work queue.
+ *
+ * `locked` restricts all four, because "existing collaborators keep their
+ * membership and their history — they simply cannot write until the policy
+ * opens again", and a vote that manufactures a work item is unambiguously a
+ * write.
+ */
+export type PolicyCapability = "annotate" | "vote" | "claim" | "submit";
+export interface AnnotationPolicyRequest {
+    policy: AnnotationPolicy;
+    /** Absent for an unauthenticated request. */
+    credential: "session" | "token" | null;
+    /** The actor's role through an unrevoked membership; null when not a member. */
+    role: Role | null;
+    capability: PolicyCapability;
+}
+/**
+ * Decide whether the policy admits this write.
+ *
+ * This answers the policy question ONLY. Scope checks, freeze, the agent pause,
+ * and rate limits are separate gates applied alongside it — a request must
+ * satisfy all of them, and each refuses with its own problem type so the caller
+ * can tell "the book is locked" from "the book is frozen" from "you are going
+ * too fast".
+ */
+export declare function checkAnnotationPolicy(request: AnnotationPolicyRequest): Decision<AnnotationPolicyDenialReason>;
+//# sourceMappingURL=annotation-policy.d.ts.map

package/dist/annotation-policy.js

@@ -0,0 +1,98 @@
+/**
+ * Annotation policy (Phase 7 contract "Restricting") — who may write to a
+ * book, and whether what they write appears immediately.
+ *
+ * | Mode                | Who may write            | Appears                    |
+ * |---------------------|--------------------------|----------------------------|
+ * | `open`              | any signed-in user       | immediately                |
+ * | `approval-gated`    | any signed-in user       | after a maintainer approves|
+ * | `collaborators-only`| members only             | immediately *(default)*    |
+ * | `locked`            | maintainers only         | immediately                |
+ *
+ * The rule is pure and lives here rather than in the API layer for the reason
+ * the contract gives for it existing at all: it is enforced SERVER-SIDE, "not
+ * merely reflected in the interface". A pure function with an exhaustive
+ * decision table is testable against every combination of mode, role, and
+ * credential kind without standing up a request, which is the only way to be
+ * confident that `locked` really does admit a maintainer's agent and really
+ * does refuse an editor.
+ *
+ * Two invariants hold across every mode and are asserted by the tests:
+ *
+ *   * **Anonymous writing is never available**, including under `open`.
+ *     Design §19.7 defers it until moderation, spam controls, privacy, and a
+ *     deletion policy all exist; Phase 7 supplies the first of the four.
+ *   * **An agent never inherits its owner's access.** An agent token writes
+ *     only through a membership of its own, which is the ordinary
+ *     scope-intersection rule of Phase 2 §3 and a deliberate grant. That is
+ *     also exactly how an author's agent keeps working under `locked`: it
+ *     holds a membership with the maintainer role, granted on purpose.
+ */
+import { ALLOWED, denied } from "./decision.js";
+export const ANNOTATION_POLICIES = [
+    "open",
+    "approval-gated",
+    "collaborators-only",
+    "locked",
+];
+/**
+ * The mode a book with no declared policy runs in: the Phase 2 behaviour,
+ * unchanged. A deployment upgrading into Phase 7 must not find its book
+ * suddenly writable by strangers, so the default is the restrictive end of the
+ * progression that people were already on — not the permissive end, and not
+ * `locked` either, which would lock out the collaborators they already have.
+ */
+export const DEFAULT_ANNOTATION_POLICY = "collaborators-only";
+export function isAnnotationPolicy(value) {
+    return typeof value === "string" && ANNOTATION_POLICIES.includes(value);
+}
+/** True when writes under this policy are queued for review rather than published. */
+export function policyRequiresApproval(policy) {
+    return policy === "approval-gated";
+}
+/**
+ * Decide whether the policy admits this write.
+ *
+ * This answers the policy question ONLY. Scope checks, freeze, the agent pause,
+ * and rate limits are separate gates applied alongside it — a request must
+ * satisfy all of them, and each refuses with its own problem type so the caller
+ * can tell "the book is locked" from "the book is frozen" from "you are going
+ * too fast".
+ */
+export function checkAnnotationPolicy(request) {
+    const { policy, credential, role, capability } = request;
+    // Invariant 1, checked before anything else so no mode can accidentally
+    // relax it: anonymous writing is unavailable everywhere.
+    if (credential === null) {
+        return denied("anonymous", "signing in is required to write to this book; anonymous contributions are not accepted in any mode");
+    }
+    if (policy === "locked") {
+        if (role === "maintainer") {
+            return ALLOWED;
+        }
+        return denied("locked", "this book is locked: only its maintainers may write. Existing collaborators keep their membership and their history, and may write again when the author reopens the policy.");
+    }
+    const isMember = role !== null;
+    if (policy === "open" || policy === "approval-gated") {
+        if (isMember) {
+            return ALLOWED;
+        }
+        // Invariant 2: a non-member agent token is NOT admitted by a permissive
+        // policy. `open` means "any signed-in GitHub user", which describes a
+        // person; an agent reaches a book through a membership granted to it on
+        // purpose, never by its owner's access spilling over.
+        if (credential === "token") {
+            return denied("members-only", "an agent token writes only through its own project membership; an open annotation policy admits signed-in people, not unenrolled agents");
+        }
+        if (capability !== "annotate") {
+            return denied("member-capability", `${capability} is a collaborator capability: an open annotation policy widens commenting and suggesting, not voting, claiming, or submitting`);
+        }
+        return ALLOWED;
+    }
+    // collaborators-only — the Phase 2 behaviour, and the default.
+    if (isMember) {
+        return ALLOWED;
+    }
+    return denied("members-only", "this book accepts writes from its collaborators only");
+}
+//# sourceMappingURL=annotation-policy.js.map

package/dist/annotation-state.d.ts

@@ -0,0 +1,32 @@
+import { ANNOTATION_STATUSES, type AnnotationStatus } from "@authorbot/schemas";
+import { type Decision } from "./decision.js";
+import type { Role } from "./scopes.js";
+export { ANNOTATION_STATUSES };
+export type { AnnotationStatus };
+/**
+ * Annotation state machine (design section 9.4; statuses per Phase 0 contract
+ * section 4). `open` fans out; `rejected -> open` is the Phase 3 maintainer
+ * reopen override (Phase 3 contract section 4); every other status is
+ * terminal. The reanchor flow (`needs_reanchor -> open`) is intentionally not
+ * legal yet — adding transitions later is additive.
+ */
+export declare const ANNOTATION_TRANSITIONS: Readonly<Record<AnnotationStatus, readonly AnnotationStatus[]>>;
+export declare function canTransitionAnnotation(from: AnnotationStatus, to: AnnotationStatus): boolean;
+export type AnnotationTransitionDenialReason = "illegal-transition";
+/** Typed decision for a requested annotation status change. */
+export declare function transitionAnnotation(from: AnnotationStatus, to: AnnotationStatus): Decision<AnnotationTransitionDenialReason>;
+export type WithdrawDenialReason = "not-author-or-maintainer" | "illegal-transition";
+/**
+ * Withdraw authorization rule (Phase 2 contract section 4): withdraw is
+ * author-or-maintainer, and only an `open` annotation can be withdrawn.
+ * `annotationAuthor` and `actor` are canonical actor refs
+ * (`<namespace>:<identifier>`, Phase 0 contract section 2); comparison is
+ * exact string equality.
+ */
+export declare function authorizeAnnotationWithdraw(input: {
+    annotationAuthor: string;
+    annotationStatus: AnnotationStatus;
+    actor: string;
+    actorRole: Role;
+}): Decision<WithdrawDenialReason>;
+//# sourceMappingURL=annotation-state.d.ts.map

package/dist/annotation-state.js

@@ -0,0 +1,58 @@
+import { ANNOTATION_STATUSES } from "@authorbot/schemas";
+import { ALLOWED, denied } from "./decision.js";
+export { ANNOTATION_STATUSES };
+/**
+ * Annotation state machine (design section 9.4; statuses per Phase 0 contract
+ * section 4). `open` fans out; `rejected -> open` is the Phase 3 maintainer
+ * reopen override (Phase 3 contract section 4); every other status is
+ * terminal. The reanchor flow (`needs_reanchor -> open`) is intentionally not
+ * legal yet — adding transitions later is additive.
+ */
+export const ANNOTATION_TRANSITIONS = Object.freeze({
+    open: [
+        "work_item_created",
+        "accepted",
+        "resolved",
+        "rejected",
+        "withdrawn",
+        "superseded",
+        "orphaned",
+        "needs_reanchor",
+    ],
+    work_item_created: [],
+    accepted: [],
+    resolved: [],
+    rejected: ["open"],
+    withdrawn: [],
+    superseded: [],
+    orphaned: [],
+    needs_reanchor: [],
+});
+export function canTransitionAnnotation(from, to) {
+    return ANNOTATION_TRANSITIONS[from].includes(to);
+}
+/** Typed decision for a requested annotation status change. */
+export function transitionAnnotation(from, to) {
+    if (canTransitionAnnotation(from, to)) {
+        return ALLOWED;
+    }
+    return denied("illegal-transition", `annotation status cannot change from "${from}" to "${to}"`);
+}
+/**
+ * Withdraw authorization rule (Phase 2 contract section 4): withdraw is
+ * author-or-maintainer, and only an `open` annotation can be withdrawn.
+ * `annotationAuthor` and `actor` are canonical actor refs
+ * (`<namespace>:<identifier>`, Phase 0 contract section 2); comparison is
+ * exact string equality.
+ */
+export function authorizeAnnotationWithdraw(input) {
+    if (input.actor !== input.annotationAuthor && input.actorRole !== "maintainer") {
+        return denied("not-author-or-maintainer", "only the annotation author or a maintainer may withdraw an annotation");
+    }
+    const transition = transitionAnnotation(input.annotationStatus, "withdrawn");
+    if (!transition.allowed) {
+        return denied("illegal-transition", `annotation with status "${input.annotationStatus}" cannot be withdrawn`);
+    }
+    return ALLOWED;
+}
+//# sourceMappingURL=annotation-state.js.map

package/dist/commands.d.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+/**
+ * Command validators (Phase 2 contract section 4). A command is the API
+ * payload plus its route parameters merged by the API layer (e.g. the
+ * `chapterId` from the URL joins the annotation payload), so validation of a
+ * whole logical command lives in one place. Markdown safety of bodies (raw
+ * HTML, URL schemes) stays with `@authorbot/markdown` at the API layer; this
+ * package enforces shape, sizes, and cross-field rules only.
+ */
+/** UTF-8 byte length without relying on host globals (pure, worker-safe). */
+export declare function utf8ByteLength(value: string): number;
+/** Body limit (contract section 4): Markdown <= 32 KiB, measured in UTF-8 bytes. */
+export declare const MAX_BODY_BYTES: number;
+/**
+ * Canonical body form: CRLF folded to LF, leading/trailing whitespace
+ * trimmed. This is exactly the normalization the artifact renderer applies
+ * (repo-coordinator render.ts) and the repo reader re-applies on read, so
+ * normalizing once at intake keeps the DB row, the committed artifact, and a
+ * rebuilt projection byte-identical (a projection rebuild must not change
+ * annotation/reply bodies served by the API).
+ */
+export declare function normalizeBody(value: string): string;
+export declare const bodySchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/** Range target with the contract's ordering rule: `textPosition.end > start`. */
+export declare const orderedRangeTargetSchema: z.ZodObject<{
+    blockId: z.ZodString;
+    textPosition: z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strict>;
+    textQuote: z.ZodObject<{
+        exact: z.ZodString;
+        prefix: z.ZodOptional<z.ZodString>;
+        suffix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * `POST .../chapters/{chapterId}/annotations` (contract section 4).
+ * `target` is required for `range` (blockId + textPosition + textQuote) and
+ * `block` (blockId only) scopes and forbidden for `chapter` scope. Whether
+ * the chapter/revision/block actually exist is the API's projection check.
+ */
+export declare const createAnnotationCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    scope: z.ZodLiteral<"range">;
+    target: z.ZodObject<{
+        blockId: z.ZodString;
+        textPosition: z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strict>;
+        textQuote: z.ZodObject<{
+            exact: z.ZodString;
+            prefix: z.ZodOptional<z.ZodString>;
+            suffix: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    chapterId: z.ZodString;
+    kind: z.ZodEnum<{
+        comment: "comment";
+        suggestion: "suggestion";
+    }>;
+    chapterRevision: z.ZodNumber;
+    body: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>, z.ZodObject<{
+    scope: z.ZodLiteral<"block">;
+    target: z.ZodObject<{
+        blockId: z.ZodString;
+    }, z.core.$strict>;
+    chapterId: z.ZodString;
+    kind: z.ZodEnum<{
+        comment: "comment";
+        suggestion: "suggestion";
+    }>;
+    chapterRevision: z.ZodNumber;
+    body: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>, z.ZodObject<{
+    scope: z.ZodLiteral<"chapter">;
+    chapterId: z.ZodString;
+    kind: z.ZodEnum<{
+        comment: "comment";
+        suggestion: "suggestion";
+    }>;
+    chapterRevision: z.ZodNumber;
+    body: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>], "scope">;
+export type CreateAnnotationCommand = z.infer<typeof createAnnotationCommandSchema>;
+/**
+ * `POST .../annotations/{annotationId}/replies`. The contract pins no reply
+ * payload; this package pins `{ body, parentReplyId? }` with the same 32 KiB
+ * body rule as annotations.
+ */
+export declare const createReplyCommandSchema: z.ZodObject<{
+    annotationId: z.ZodString;
+    parentReplyId: z.ZodOptional<z.ZodString>;
+    body: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>;
+export type CreateReplyCommand = z.infer<typeof createReplyCommandSchema>;
+/** Token display-name bound (not contract-pinned; chosen for UI sanity). */
+export declare const MAX_TOKEN_NAME_LENGTH = 100;
+/**
+ * `POST .../agent-tokens` (contract section 3): name, scopes ⊆ known scopes
+ * (non-empty, no duplicates), expiry <= 90 days (default 30).
+ */
+export declare const mintAgentTokenCommandSchema: z.ZodObject<{
+    name: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "chapters:read": "chapters:read";
+        "annotations:read": "annotations:read";
+        "annotations:write": "annotations:write";
+        "work:read": "work:read";
+        "work:claim": "work:claim";
+        "submissions:write": "submissions:write";
+        "tokens:manage": "tokens:manage";
+        "members:manage": "members:manage";
+    }>>;
+    expiresInDays: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type MintAgentTokenCommand = z.infer<typeof mintAgentTokenCommandSchema>;
+export type MintAgentTokenCommandInput = z.input<typeof mintAgentTokenCommandSchema>;
+/**
+ * `POST .../annotations/{annotationId}/withdraw`. The HTTP body is empty;
+ * the command is the route parameter. Authorization (author-or-maintainer)
+ * is `authorizeAnnotationWithdraw` in annotation-state.
+ */
+export declare const withdrawAnnotationCommandSchema: z.ZodObject<{
+    annotationId: z.ZodString;
+}, z.core.$strict>;
+export type WithdrawAnnotationCommand = z.infer<typeof withdrawAnnotationCommandSchema>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { annotationKindSchema, blockTargetSchema, rangeTargetSchema, uuidv7Schema, } from "@authorbot/schemas";
+import { scopeSchema } from "./scopes.js";
+/**
+ * Command validators (Phase 2 contract section 4). A command is the API
+ * payload plus its route parameters merged by the API layer (e.g. the
+ * `chapterId` from the URL joins the annotation payload), so validation of a
+ * whole logical command lives in one place. Markdown safety of bodies (raw
+ * HTML, URL schemes) stays with `@authorbot/markdown` at the API layer; this
+ * package enforces shape, sizes, and cross-field rules only.
+ */
+/** UTF-8 byte length without relying on host globals (pure, worker-safe). */
+export function utf8ByteLength(value) {
+    let bytes = 0;
+    for (const char of value) {
+        const code = char.codePointAt(0);
+        bytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
+    }
+    return bytes;
+}
+/** Body limit (contract section 4): Markdown <= 32 KiB, measured in UTF-8 bytes. */
+export const MAX_BODY_BYTES = 32 * 1024;
+/**
+ * Canonical body form: CRLF folded to LF, leading/trailing whitespace
+ * trimmed. This is exactly the normalization the artifact renderer applies
+ * (repo-coordinator render.ts) and the repo reader re-applies on read, so
+ * normalizing once at intake keeps the DB row, the committed artifact, and a
+ * rebuilt projection byte-identical (a projection rebuild must not change
+ * annotation/reply bodies served by the API).
+ */
+export function normalizeBody(value) {
+    return value.replace(/\r\n/g, "\n").trim();
+}
+export const bodySchema = z
+    .string()
+    .transform(normalizeBody)
+    .refine((value) => value.length > 0, "body must not be empty")
+    .refine((value) => utf8ByteLength(value) <= MAX_BODY_BYTES, `body must be at most ${MAX_BODY_BYTES} bytes of UTF-8`);
+/** Range target with the contract's ordering rule: `textPosition.end > start`. */
+export const orderedRangeTargetSchema = rangeTargetSchema.refine((target) => target.textPosition.end > target.textPosition.start, { path: ["textPosition", "end"], message: "textPosition.end must be greater than textPosition.start" });
+const createAnnotationBase = {
+    chapterId: uuidv7Schema,
+    kind: annotationKindSchema,
+    chapterRevision: z.number().int().min(1),
+    body: bodySchema,
+};
+/**
+ * `POST .../chapters/{chapterId}/annotations` (contract section 4).
+ * `target` is required for `range` (blockId + textPosition + textQuote) and
+ * `block` (blockId only) scopes and forbidden for `chapter` scope. Whether
+ * the chapter/revision/block actually exist is the API's projection check.
+ */
+export const createAnnotationCommandSchema = z.discriminatedUnion("scope", [
+    z.strictObject({
+        ...createAnnotationBase,
+        scope: z.literal("range"),
+        target: orderedRangeTargetSchema,
+    }),
+    z.strictObject({
+        ...createAnnotationBase,
+        scope: z.literal("block"),
+        target: blockTargetSchema,
+    }),
+    z.strictObject({
+        ...createAnnotationBase,
+        scope: z.literal("chapter"),
+    }),
+]);
+/**
+ * `POST .../annotations/{annotationId}/replies`. The contract pins no reply
+ * payload; this package pins `{ body, parentReplyId? }` with the same 32 KiB
+ * body rule as annotations.
+ */
+export const createReplyCommandSchema = z.strictObject({
+    annotationId: uuidv7Schema,
+    parentReplyId: uuidv7Schema.optional(),
+    body: bodySchema,
+});
+/** Token display-name bound (not contract-pinned; chosen for UI sanity). */
+export const MAX_TOKEN_NAME_LENGTH = 100;
+/**
+ * `POST .../agent-tokens` (contract section 3): name, scopes ⊆ known scopes
+ * (non-empty, no duplicates), expiry <= 90 days (default 30).
+ */
+export const mintAgentTokenCommandSchema = z.strictObject({
+    name: z
+        .string()
+        .min(1, "name must not be empty")
+        .max(MAX_TOKEN_NAME_LENGTH, `name must be at most ${MAX_TOKEN_NAME_LENGTH} characters`),
+    scopes: z
+        .array(scopeSchema)
+        .min(1, "at least one scope is required")
+        .refine((scopes) => new Set(scopes).size === scopes.length, "scopes must not contain duplicates"),
+    expiresInDays: z.number().int().min(1).max(90).default(30),
+});
+/**
+ * `POST .../annotations/{annotationId}/withdraw`. The HTTP body is empty;
+ * the command is the route parameter. Authorization (author-or-maintainer)
+ * is `authorizeAnnotationWithdraw` in annotation-state.
+ */
+export const withdrawAnnotationCommandSchema = z.strictObject({
+    annotationId: uuidv7Schema,
+});
+//# sourceMappingURL=commands.js.map

package/dist/decision-support.d.ts

@@ -0,0 +1,33 @@
+export { DECISION_RESULTS, decisionResultSchema } from "@authorbot/schemas";
+export type { DecisionResult } from "@authorbot/schemas";
+/**
+ * Sticky decision `support_changed` tracking (Phase 3 contract section 4,
+ * design section 11.3). Later vote changes never delete a decision or its
+ * work item; the decision only gains/loses a `support_changed` mark as the
+ * live aggregate stops/starts satisfying the rule, with an event on each
+ * flip. The original threshold-crossing metric snapshot is preserved
+ * elsewhere (the decision row/artifact) and never rewritten here.
+ */
+/** Event emitted whenever the mark flips (contract section 5). */
+export declare const DECISION_SUPPORT_CHANGED_EVENT: "decision_support_changed";
+export type SupportChangeTransition = "marked" | "cleared" | "unchanged";
+export interface SupportChangeOutcome {
+    /** The mark after applying the rule outcome. */
+    readonly supportChanged: boolean;
+    readonly transition: SupportChangeTransition;
+    /** True exactly when a `decision_support_changed` event must be emitted. */
+    readonly emitEvent: boolean;
+}
+/**
+ * Pure transition: given the decision's current mark and whether the live
+ * aggregate still satisfies the rule, decide the new mark.
+ *
+ * - satisfied + marked   → `cleared` (support returned)
+ * - unsatisfied + unmarked → `marked` (support fell away)
+ * - otherwise            → `unchanged`, no event
+ */
+export declare function resolveSupportChange(input: {
+    supportChanged: boolean;
+    ruleSatisfied: boolean;
+}): SupportChangeOutcome;
+//# sourceMappingURL=decision-support.d.ts.map

package/dist/decision-support.js

@@ -0,0 +1,29 @@
+export { DECISION_RESULTS, decisionResultSchema } from "@authorbot/schemas";
+/**
+ * Sticky decision `support_changed` tracking (Phase 3 contract section 4,
+ * design section 11.3). Later vote changes never delete a decision or its
+ * work item; the decision only gains/loses a `support_changed` mark as the
+ * live aggregate stops/starts satisfying the rule, with an event on each
+ * flip. The original threshold-crossing metric snapshot is preserved
+ * elsewhere (the decision row/artifact) and never rewritten here.
+ */
+/** Event emitted whenever the mark flips (contract section 5). */
+export const DECISION_SUPPORT_CHANGED_EVENT = "decision_support_changed";
+/**
+ * Pure transition: given the decision's current mark and whether the live
+ * aggregate still satisfies the rule, decide the new mark.
+ *
+ * - satisfied + marked   → `cleared` (support returned)
+ * - unsatisfied + unmarked → `marked` (support fell away)
+ * - otherwise            → `unchanged`, no event
+ */
+export function resolveSupportChange(input) {
+    if (input.ruleSatisfied && input.supportChanged) {
+        return { supportChanged: false, transition: "cleared", emitEvent: true };
+    }
+    if (!input.ruleSatisfied && !input.supportChanged) {
+        return { supportChanged: true, transition: "marked", emitEvent: true };
+    }
+    return { supportChanged: input.supportChanged, transition: "unchanged", emitEvent: false };
+}
+//# sourceMappingURL=decision-support.js.map

package/dist/decision.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Typed authorization/transition decisions (Phase 2 contract section 3).
+ * Every domain rule that can refuse returns `allowed | denied(reason)` so the
+ * API layer can map reasons to problem+json types without string matching.
+ */
+export interface Allowed {
+    readonly allowed: true;
+}
+export interface Denied<TReason extends string = string> {
+    readonly allowed: false;
+    readonly reason: TReason;
+    /** Human-readable explanation; safe to surface (never contains secrets). */
+    readonly message: string;
+}
+export type Decision<TReason extends string = string> = Allowed | Denied<TReason>;
+export declare const ALLOWED: Allowed;
+export declare function denied<TReason extends string>(reason: TReason, message: string): Denied<TReason>;
+//# sourceMappingURL=decision.d.ts.map

package/dist/decision.js

@@ -0,0 +1,10 @@
+/**
+ * Typed authorization/transition decisions (Phase 2 contract section 3).
+ * Every domain rule that can refuse returns `allowed | denied(reason)` so the
+ * API layer can map reasons to problem+json types without string matching.
+ */
+export const ALLOWED = Object.freeze({ allowed: true });
+export function denied(reason, message) {
+    return { allowed: false, reason, message };
+}
+//# sourceMappingURL=decision.js.map