@tomradex/domain 0.0.0-stage → 0.2.0

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/delivery.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+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>;
+}
+//# 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,53 @@
+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);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,99 @@
+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";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/fields.d.ts

@@ -0,0 +1,54 @@
+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;
+}
+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

package/dist/fields.js

@@ -0,0 +1,104 @@
+import { ITEM_STATUSES } from "./types.js";
+/** The types a user may create. The rest are built-in only. */
+export const CUSTOM_FIELD_TYPES = ["text", "number", "date", "select", "checkbox"];
+/** A checkbox is stored only when ticked; unticked is the absence of a value. */
+export const CHECKED = 1;
+const PRIORITY_NAMES = ["None", "Low", "Medium", "High", "Urgent"];
+const STATUS_NAMES = { backlog: "Backlog", todo: "To Do", doing: "Doing", verifying: "Verifying", done: "Done", cancelled: "Cancelled" };
+const staticOptions = (ids, name) => ids.map((id, rank) => ({ id, name: name(id), description: null, rank }));
+const builtin = (id, name, type, rank, extra = {}) => ({
+    id,
+    projectId: null,
+    name,
+    type,
+    builtin: true,
+    options: extra.options ?? [],
+    optionsFrom: extra.optionsFrom,
+    readonly: extra.readonly ?? false,
+    can: extra.can ?? { filter: true, sort: true, group: type === "select" || type === "item" },
+    rank
+});
+/** The fields every project has, in display order. Ids are reserved: a custom field can never claim one. */
+export const BUILTIN_FIELDS = [
+    builtin("title", "Title", "text", 0, { can: { filter: true, sort: true, group: false } }),
+    builtin("status", "Status", "select", 1, { options: staticOptions(ITEM_STATUSES, (s) => STATUS_NAMES[s]) }),
+    builtin("workType", "Work type", "select", 9, { options: staticOptions(["coding", "general"], (s) => s === "coding" ? "Coding" : "General") }),
+    // Urgent first: the column order a priority board reads in.
+    builtin("priority", "Priority", "select", 2, { options: staticOptions(["4", "3", "2", "1", "0"], (p) => PRIORITY_NAMES[Number(p)]) }),
+    builtin("epic", "Epic", "item", 3, { optionsFrom: "epics" }),
+    builtin("labels", "Labels", "labels", 4, { can: { filter: true, sort: false, group: false } }),
+    builtin("board", "Workstream", "select", 5, { optionsFrom: "boards" }),
+    builtin("updated", "Updated", "date", 6, { readonly: true, can: { filter: true, sort: true, group: false } }),
+    builtin("key", "Key", "number", 7, { readonly: true, can: { filter: false, sort: true, group: false } }),
+    builtin("provenance", "Last write", "select", 8, {
+        readonly: true,
+        options: staticOptions(["human", "ai", "sync", "locked"], (p) => ({ human: "human", ai: "ai", sync: "sync", locked: "human-locked" })[p])
+    })
+];
+export const BUILTIN_FIELD_IDS = new Set(BUILTIN_FIELDS.map((f) => f.id));
+export const isBuiltinFieldId = (id) => BUILTIN_FIELD_IDS.has(id);
+/** The empty-value sentinel a group key uses, and the literal a filter may name. */
+export const EMPTY_KEY = "none";
+const provenanceOf = (item) => item.humanLocked ? "locked" : item.updatedBy.startsWith("ai:") ? "ai" : item.updatedBy.startsWith("sync:") ? "sync" : "human";
+/**
+ * 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 function fieldValueOf(item, fieldId) {
+    switch (fieldId) {
+        case "title":
+            return item.title;
+        case "status":
+            return item.status;
+        case "workType":
+            return item.workType;
+        case "priority":
+            return String(item.priority);
+        case "epic":
+            return item.parentId;
+        case "labels":
+            return item.labels;
+        case "board":
+            return item.boardId;
+        case "updated":
+            return item.updatedAt;
+        case "key":
+            return item.keyNum;
+        case "provenance":
+            return provenanceOf(item);
+        default:
+            return item.fields[fieldId] ?? null;
+    }
+}
+/** Which column or swimlane an item falls into for a groupable field. */
+export function groupKeyOf(item, fieldId) {
+    const v = fieldValueOf(item, fieldId);
+    if (v === null || Array.isArray(v))
+        return EMPTY_KEY;
+    return String(v);
+}
+/** The patch a drop into `key` writes, for a groupable field; null when the field cannot be written. */
+export function patchForGroup(fieldId, key, def) {
+    const empty = key === EMPTY_KEY;
+    switch (fieldId) {
+        case "status":
+            return empty ? null : { status: key };
+        case "workType":
+            return key === "coding" || key === "general" ? { workType: key } : null;
+        case "priority":
+            return empty ? null : { priority: Number(key) };
+        case "epic":
+            return { parentId: empty ? null : key };
+        case "board":
+            return empty ? null : { boardId: key };
+        default:
+            if (!def || def.builtin)
+                return null;
+            if (def.type === "select")
+                return { fields: { [fieldId]: empty ? null : key } };
+            if (def.type === "checkbox")
+                return { fields: { [fieldId]: empty ? null : CHECKED } };
+            return null;
+    }
+}
+//# sourceMappingURL=fields.js.map

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./delivery.js";
+export * from "./errors.js";
+export * from "./schema.js";
+export * from "./derive.js";
+export * from "./fields.js";
+export * from "./query.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./delivery.js";
+export * from "./errors.js";
+export * from "./schema.js";
+export * from "./derive.js";
+export * from "./fields.js";
+export * from "./query.js";
+//# sourceMappingURL=index.js.map