@tomradex/domain 0.0.0-stage → 0.2.16

package/LICENSE

@@ -0,0 +1,204 @@
+Copyright 2026 Haoyuan Tang
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @tomradex/domain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The types a Tomrade plugin reads: issues (`Item`), fields, boards, views, projects and the history (`OplogEntry`), with the zod schemas and typed errors behind them. Plugins normally get these through [`@tomradex/plugin-sdk`](https://www.npmjs.com/package/@tomradex/plugin-sdk), which re-exports them.

package/dist/attachments.d.ts

@@ -0,0 +1,19 @@
+/**
+ * How a ticket body points at a file of the project's Files store: by id, so a
+ * rename or a move in Files never breaks the link and never rewrites the body.
+ */
+export declare const FILE_LINK = "tomrade-file://";
+/** Each file id the text links to, once, in order of first mention. */
+export declare function linkedFileIds(text: string | null | undefined): string[];
+/** A linked file as an agent can use it: where it is now and what it is. */
+export interface FileDescription {
+    fileId: string;
+    /** Relative to the Files store root. */
+    path: string;
+    name: string;
+    mime: string;
+    size: number;
+    /** On this machine, for engines that read files themselves; null when the store has no folder here. */
+    localPath: string | null;
+}
+//# sourceMappingURL=attachments.d.ts.map

package/dist/attachments.js

@@ -0,0 +1,13 @@
+/**
+ * How a ticket body points at a file of the project's Files store: by id, so a
+ * rename or a move in Files never breaks the link and never rewrites the body.
+ */
+export const FILE_LINK = "tomrade-file://";
+const LINKED = /tomrade-file:\/\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/gi;
+/** Each file id the text links to, once, in order of first mention. */
+export function linkedFileIds(text) {
+    if (!text)
+        return [];
+    return [...new Set([...text.matchAll(LINKED)].map((m) => m[1].toLowerCase()))];
+}
+//# sourceMappingURL=attachments.js.map

package/dist/delivery.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import type { FileDescription } from "./attachments.js";
+import type { Author } from "./types.js";
+/** Metadata only. File bytes and immutable versions belong to the Files plugin. */
+export interface FileReference {
+    fileId: string;
+    versionId: string;
+}
+export interface DeliveryResource {
+    id: string;
+    name: string;
+    role: "input" | "output";
+    deliveryId: string | null;
+    file: FileReference;
+    createdBy: Author;
+    createdAt: number;
+}
+export interface DeliverySubmission {
+    id: string;
+    deliveryId: string;
+    report: string;
+    artifactIds: string[];
+    submittedBy: Author;
+    submittedAt: number;
+}
+export interface DeliveryReview {
+    id: string;
+    submissionId: string;
+    decision: "accepted" | "changes-requested";
+    comment: string;
+    reviewedBy: "human";
+    reviewedAt: number;
+}
+export interface TicketEvidence {
+    resources: DeliveryResource[];
+    submissions: DeliverySubmission[];
+    reviews: DeliveryReview[];
+}
+export declare const emptyEvidence: () => TicketEvidence;
+export declare const fileReferenceSchema: z.ZodObject<{
+    fileId: z.ZodString;
+    versionId: z.ZodString;
+}, z.core.$strip>;
+export declare const addResourceSchema: z.ZodObject<{
+    name: z.ZodString;
+    role: z.ZodEnum<{
+        input: "input";
+        output: "output";
+    }>;
+    file: z.ZodObject<{
+        fileId: z.ZodString;
+        versionId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const submitDeliverySchema: z.ZodObject<{
+    report: z.ZodString;
+    artifactIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const reviewDeliverySchema: z.ZodObject<{
+    submissionId: z.ZodString;
+    decision: z.ZodEnum<{
+        accepted: "accepted";
+        "changes-requested": "changes-requested";
+    }>;
+    comment: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/** The future Files plugin supplies this resolver; no fallback file store exists. */
+export interface FilesResolver {
+    getVersion(projectId: string, reference: FileReference): Promise<FileReference | null>;
+    /** The files behind these ids as they are now; an id with no file here is left out. */
+    describe(projectId: string, fileIds: string[]): Promise<FileDescription[]>;
+}
+//# sourceMappingURL=delivery.d.ts.map

package/dist/delivery.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export const emptyEvidence = () => ({ resources: [], submissions: [], reviews: [] });
+export const fileReferenceSchema = z.object({ fileId: z.string().min(1), versionId: z.string().min(1) });
+export const addResourceSchema = z.object({ name: z.string().trim().min(1), role: z.enum(["input", "output"]), file: fileReferenceSchema });
+export const submitDeliverySchema = z.object({ report: z.string().trim().min(1), artifactIds: z.array(z.string()).default([]) });
+export const reviewDeliverySchema = z.object({ submissionId: z.string().min(1), decision: z.enum(["accepted", "changes-requested"]), comment: z.string().default("") });
+//# sourceMappingURL=delivery.js.map

package/dist/derive.d.ts

@@ -0,0 +1,8 @@
+import type { Author, Item, Provenance } from "./types.js";
+export declare const isAi: (by: Author | string) => boolean;
+export declare const isSync: (by: Author | string) => boolean;
+/** Derived, never stored: a locked item reads as locked whoever wrote it last. */
+export declare function provenanceOf(item: Pick<Item, "humanLocked" | "updatedBy">): Provenance;
+/** 'Tomrade Next' -> 'TOM'. Falls back to a generic prefix for nameless input. */
+export declare function keyPrefixFor(name: string): string;
+//# sourceMappingURL=derive.d.ts.map

package/dist/derive.js

@@ -0,0 +1,14 @@
+export const isAi = (by) => by.startsWith("ai:");
+export const isSync = (by) => by.startsWith("sync:");
+/** Derived, never stored: a locked item reads as locked whoever wrote it last. */
+export function provenanceOf(item) {
+    if (item.humanLocked)
+        return "locked";
+    return isAi(item.updatedBy) ? "ai" : isSync(item.updatedBy) ? "sync" : "human";
+}
+/** 'Tomrade Next' -> 'TOM'. Falls back to a generic prefix for nameless input. */
+export function keyPrefixFor(name) {
+    const letters = name.toUpperCase().replace(/[^A-Z]/g, "");
+    return letters.slice(0, 3) || "ISS";
+}
+//# sourceMappingURL=derive.js.map

package/dist/errors.d.ts

@@ -0,0 +1,75 @@
+export declare class ConflictError extends Error {
+    readonly itemId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    constructor(itemId: string, expectedVersion: number, actualVersion: number);
+}
+export declare class HumanLockedError extends Error {
+    readonly itemId: string;
+    readonly fields: string[];
+    constructor(itemId: string, fields: string[]);
+}
+export declare class NotFoundError extends Error {
+    readonly itemId: string;
+    constructor(itemId: string);
+}
+/** The permanent delete refused because the caller is not a human. */
+export declare class PurgeNotPermittedError extends Error {
+    readonly itemId: string;
+    readonly by: string;
+    constructor(itemId: string, by: string);
+}
+/** An extension claimed a human's authorship outside a human-initiated call. */
+export declare class ExtensionAuthorError extends Error {
+    readonly pluginId: string;
+    readonly entity: string;
+    readonly op: string;
+    constructor(pluginId: string, entity: string, op: string);
+}
+/** A blocks edit refused because "blocked until done" only means something on a DAG. */
+export declare class DependencyCycleError extends Error {
+    readonly itemId: string;
+    readonly path: string[];
+    constructor(itemId: string, path: string[]);
+}
+/** A destructive write refused because something still depends on the target. */
+export declare class InUseError extends Error {
+    readonly entityId: string;
+    readonly reason: string;
+    constructor(entityId: string, reason: string);
+}
+/** A custom-field write refused: unknown field, wrong type, or an option the field does not have. */
+export declare class FieldValueError extends Error {
+    readonly fieldId: string;
+    readonly reason: string;
+    constructor(fieldId: string, reason: string);
+}
+/** A field definition change refused: a built-in, a taken name, an option on a non-select. */
+export declare class FieldDefinitionError extends Error {
+    readonly fieldId: string;
+    readonly reason: string;
+    constructor(fieldId: string, reason: string);
+}
+/**
+ * What a failed model call means for the person — each wants a different fix: the key, the address, a wait.
+ * `slow`: the model was reached but gave no answer in time; only a check that waits for one says it.
+ */
+export type ModelErrorKind = "auth" | "quota" | "rate" | "model" | "server" | "network" | "slow" | "other";
+/** Why a model turned a working key down: the wrong API for it, not open to this key's tier or account, or not known. */
+export type ModelRefusal = "method" | "tier" | "unknown";
+export declare function modelRefusal(message: string): ModelRefusal | null;
+/** Only a key the provider calls wrong or missing is `auth`; a model it will not serve this key is `model`, even on a 403. */
+export declare function modelErrorKind(message: string): ModelErrorKind;
+/** The provider's own words in a failed call's detail (its JSON `message`), or null; cut short where the detail was. */
+export declare function providerMessage(detail: string): string | null;
+/**
+ * An undo aimed at one write — a toast's — refused because the thing changed
+ * again since. The marker survives IPC's message wrapping, so the renderer can
+ * say it in the person's language.
+ */
+export declare const STALE_UNDO = "[stale-undo]";
+export declare class StaleUndoError extends Error {
+    readonly entityId: string;
+    constructor(entityId: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,155 @@
+export class ConflictError extends Error {
+    itemId;
+    expectedVersion;
+    actualVersion;
+    constructor(itemId, expectedVersion, actualVersion) {
+        super(`Item ${itemId} version conflict: expected ${expectedVersion}, got ${actualVersion} (it was edited by someone else)`);
+        this.itemId = itemId;
+        this.expectedVersion = expectedVersion;
+        this.actualVersion = actualVersion;
+        this.name = "ConflictError";
+    }
+}
+export class HumanLockedError extends Error {
+    itemId;
+    fields;
+    constructor(itemId, fields) {
+        super(`Item ${itemId} is human-locked; AI may not edit fields: ${fields.join(", ")}`);
+        this.itemId = itemId;
+        this.fields = fields;
+        this.name = "HumanLockedError";
+    }
+}
+export class NotFoundError extends Error {
+    itemId;
+    constructor(itemId) {
+        super(`Item ${itemId} not found`);
+        this.itemId = itemId;
+        this.name = "NotFoundError";
+    }
+}
+/** The permanent delete refused because the caller is not a human. */
+export class PurgeNotPermittedError extends Error {
+    itemId;
+    by;
+    constructor(itemId, by) {
+        super(`Item ${itemId} may only be permanently deleted by a human; ${by} must use the reversible delete`);
+        this.itemId = itemId;
+        this.by = by;
+        this.name = "PurgeNotPermittedError";
+    }
+}
+/** An extension claimed a human's authorship outside a human-initiated call. */
+export class ExtensionAuthorError extends Error {
+    pluginId;
+    entity;
+    op;
+    constructor(pluginId, entity, op) {
+        super(`Extension ${pluginId} may not write as a human (${entity} ${op}) unless a person asked for it`);
+        this.pluginId = pluginId;
+        this.entity = entity;
+        this.op = op;
+        this.name = "ExtensionAuthorError";
+    }
+}
+/** A blocks edit refused because "blocked until done" only means something on a DAG. */
+export class DependencyCycleError extends Error {
+    itemId;
+    path;
+    constructor(itemId, path) {
+        super(`Blocking ${path[path.length - 1]} would close a cycle: ${path.join(" → ")}`);
+        this.itemId = itemId;
+        this.path = path;
+        this.name = "DependencyCycleError";
+    }
+}
+/** A destructive write refused because something still depends on the target. */
+export class InUseError extends Error {
+    entityId;
+    reason;
+    constructor(entityId, reason) {
+        super(reason);
+        this.entityId = entityId;
+        this.reason = reason;
+        this.name = "InUseError";
+    }
+}
+/** A custom-field write refused: unknown field, wrong type, or an option the field does not have. */
+export class FieldValueError extends Error {
+    fieldId;
+    reason;
+    constructor(fieldId, reason) {
+        super(`Field ${fieldId}: ${reason}`);
+        this.fieldId = fieldId;
+        this.reason = reason;
+        this.name = "FieldValueError";
+    }
+}
+/** A field definition change refused: a built-in, a taken name, an option on a non-select. */
+export class FieldDefinitionError extends Error {
+    fieldId;
+    reason;
+    constructor(fieldId, reason) {
+        super(`Field ${fieldId}: ${reason}`);
+        this.fieldId = fieldId;
+        this.reason = reason;
+        this.name = "FieldDefinitionError";
+    }
+}
+const BAD_KEY = /\b401\b|authenticat|unauthori[sz]ed|invalid[ _-]?(api[ _-]?)?key|incorrect api key|api[ _-]?key[ _-]?(not valid|invalid|expired|missing|required)|(missing|no) api[ _-]?key/i;
+export function modelRefusal(message) {
+    if (/not supported for (generateContent|this (api|method|endpoint))|not a chat model|only supported (in|on|by) (the )?(v1\/)?responses|not supported (in|on|by) (the )?(v1\/)?chat\/completions|does not support (chat|generateContent)/i.test(message))
+        return "method";
+    if (/model.{0,40}(not found|does not exist|not exist|unknown)|no such model|unknown model|model_not_found/i.test(message) && !/not have access to model/i.test(message))
+        return "unknown";
+    if (/free[ _-]?tier\w*.{0,80}\blimit: ?0\b|not available (on|for|in) (the |your |this )?(free |current )?(tier|plan)|not have access to (the |this )?model|not have permission to (use|access) (the |this )?model|not allow-?listed|model.{0,60}(not available|unavailable) (to|for) (you|this)/i.test(message))
+        return "tier";
+    return null;
+}
+/** Only a key the provider calls wrong or missing is `auth`; a model it will not serve this key is `model`, even on a 403. */
+export function modelErrorKind(message) {
+    if (BAD_KEY.test(message))
+        return "auth";
+    if (modelRefusal(message))
+        return "model";
+    if (/\b403\b|api key|permission denied|forbidden/i.test(message))
+        return "auth";
+    if (/\b402\b|insufficient|balance|quota|billing|credit/i.test(message))
+        return "quota";
+    if (/\b429\b|rate.?limit|too many requests/i.test(message))
+        return "rate";
+    if (/\b404\b|model.{0,40}(not found|does not exist|not exist|unknown|invalid)|no such model|unknown model/i.test(message))
+        return "model";
+    if (/\b5\d\d\b|overloaded|bad gateway|service unavailable/i.test(message))
+        return "server";
+    if (/fetch failed|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|network|timed? ?out|socket hang up|certificate/i.test(message))
+        return "network";
+    return "other";
+}
+/** The provider's own words in a failed call's detail (its JSON `message`), or null; cut short where the detail was. */
+export function providerMessage(detail) {
+    const found = /"message"\s*:\s*"((?:[^"\\]|\\.)*)("|$)/.exec(detail);
+    if (!found?.[1].trim())
+        return null;
+    let said = found[1];
+    try {
+        said = JSON.parse(`"${said.replace(/\\$/, "")}"`);
+    }
+    catch { }
+    return found[2] ? said : `${said}…`;
+}
+/**
+ * An undo aimed at one write — a toast's — refused because the thing changed
+ * again since. The marker survives IPC's message wrapping, so the renderer can
+ * say it in the person's language.
+ */
+export const STALE_UNDO = "[stale-undo]";
+export class StaleUndoError extends Error {
+    entityId;
+    constructor(entityId) {
+        super(`${STALE_UNDO} ${entityId} changed again after that edit; undo it from History instead`);
+        this.entityId = entityId;
+        this.name = "StaleUndoError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/fields.d.ts

@@ -0,0 +1,58 @@
+import type { FieldValue, Item, Patch } from "./types.js";
+/**
+ * Every attribute a view can filter, sort or group by is a field. Built-in
+ * fields are columns on `items` and are the same for every project; custom
+ * fields are rows in `fields` and their values live in `item_values`.
+ */
+export type FieldType = "text" | "number" | "date" | "select" | "checkbox" | "labels" | "item";
+/** The types a user may create. The rest are built-in only. */
+export declare const CUSTOM_FIELD_TYPES: readonly FieldType[];
+/** A checkbox is stored only when ticked; unticked is the absence of a value. */
+export declare const CHECKED = 1;
+export interface FieldOption {
+    id: string;
+    name: string;
+    description: string | null;
+    rank: number;
+}
+export interface FieldDef {
+    id: string;
+    /** Null for a built-in: it exists in every project. */
+    projectId: string | null;
+    name: string;
+    type: FieldType;
+    builtin: boolean;
+    /** Fixed options for a select. Empty when they come from `optionsFrom`. */
+    options: FieldOption[];
+    /** Built-in selects whose options are rows elsewhere; the caller resolves them. */
+    optionsFrom?: "boards" | "epics";
+    /** Derived or system-owned: shown and sortable, never written. */
+    readonly: boolean;
+    can: {
+        filter: boolean;
+        sort: boolean;
+        group: boolean;
+    };
+    rank: number;
+    /** Computed by a plugin from what it keeps (a ticket's spend, say); its value rides on `item.fields` when items are read. */
+    derived?: boolean;
+    /** How a number reads: `usd` is money. */
+    unit?: "usd";
+}
+export type BuiltinFieldId = "title" | "status" | "workType" | "priority" | "epic" | "labels" | "board" | "updated" | "key" | "provenance";
+/** The fields every project has, in display order. Ids are reserved: a custom field can never claim one. */
+export declare const BUILTIN_FIELDS: readonly FieldDef[];
+export declare const BUILTIN_FIELD_IDS: Set<string>;
+export declare const isBuiltinFieldId: (id: string) => id is BuiltinFieldId;
+/** The empty-value sentinel a group key uses, and the literal a filter may name. */
+export declare const EMPTY_KEY = "none";
+/**
+ * The raw value of a field on an item, built-in or custom. Labels are the one
+ * multi-valued field; everything else is a scalar or null.
+ */
+export declare function fieldValueOf(item: Item, fieldId: string): FieldValue | FieldValue[] | null;
+/** Which column or swimlane an item falls into for a groupable field. */
+export declare function groupKeyOf(item: Item, fieldId: string): string;
+/** The patch a drop into `key` writes, for a groupable field; null when the field cannot be written. */
+export declare function patchForGroup(fieldId: string, key: string, def: FieldDef | undefined): Patch | null;
+//# sourceMappingURL=fields.d.ts.map