@oxygen-agent/cli 1.638.1 → 1.677.10

package/node_modules/@oxygen/shared/dist/collab.d.ts

@@ -0,0 +1,229 @@
+import { type TagKind } from "./tags.js";
+/**
+ * Workspace objects that can carry a comment thread or an approval request.
+ *
+ * Seeded from {@link TAG_KINDS}: anything worth labelling for a campaign is
+ * worth discussing with the client who signs that campaign off. The list is
+ * RESTATED rather than aliased because it is also a stored value — existing
+ * `ox_collab` rows pin it — so widening the tag vocabulary must be a deliberate
+ * decision here, not a silent side effect. (`subject_kind` deliberately carries
+ * no enum CHECK; 0182_collab.sql explains why, so adding a kind here needs no
+ * tenant migration.) The alignment is enforced
+ * both ways: {@link EveryTagKindIsCommentable} fails the build if a taggable
+ * kind is missing, and the paired test pins today's list exactly.
+ */
+export declare const COLLAB_SUBJECT_KINDS: readonly ["knowledge_page", "publishing_post", "sequence", "table", "workflow", "recipe", "conversation", "mailbox", "sender", "record", "domain", "project", "sender_profile", "voice_number"];
+export type CollabSubjectKind = (typeof COLLAB_SUBJECT_KINDS)[number];
+/** Compile-time assertion helper: instantiating with `false` is a type error. */
+type AssertTrue<T extends true> = T;
+/**
+ * Build-time proof that every taggable kind is also commentable. Adding a kind
+ * to {@link TAG_KINDS} without adding it here is a compile error, which is the
+ * point: the alternative is an API that accepts `--on <newkind>:<id>` and a
+ * database that rejects the insert.
+ *
+ * Divergence is legal in the other direction only — Collaboration may grow a
+ * subject kind that carries no tags.
+ */
+export type EveryTagKindIsCommentable = AssertTrue<TagKind extends CollabSubjectKind ? true : false>;
+export declare function isCollabSubjectKind(value: unknown): value is CollabSubjectKind;
+/**
+ * How each subject kind is named in output. Total over CollabSubjectKind, so
+ * adding a kind is a compile error until it is labelled — the guarantee
+ * `TAG_KIND_LABELS` had to learn the hard way when three hand-maintained copies
+ * of the same map drifted apart.
+ *
+ * `many` keeps proper nouns intact ("CRM records") so an inline count reads
+ * correctly; headings run it through {@link collabSubjectHeading}, which only
+ * uppercases a leading lowercase letter.
+ */
+export declare const COLLAB_SUBJECT_LABELS: Record<CollabSubjectKind, {
+    one: string;
+    many: string;
+}>;
+/**
+ * What a thread on each kind is usually about, for `--help` and MCP tool
+ * descriptions. Total over CollabSubjectKind for the same reason the labels
+ * are: a blind-user eval (2026-07-21) found `tags --help` still advertising 7
+ * of 13 kinds because the prose was hand-written beside a hand-maintained
+ * marker map, so six taggable kinds were invisible from the one place a user
+ * looks. Here the help text cannot omit a kind — the compiler rejects the map
+ * until the kind is glossed, and {@link COLLAB_SUBJECT_KINDS_PROSE} is DERIVED
+ * from the labels rather than typed out a second time.
+ */
+export declare const COLLAB_SUBJECT_PROSE: Record<CollabSubjectKind, string>;
+/**
+ * Every commentable kind in prose, for CLI `--help` and MCP tool descriptions.
+ * Derived from {@link COLLAB_SUBJECT_LABELS} on purpose: a hand-written copy is
+ * exactly what drifted in the tags help.
+ */
+export declare const COLLAB_SUBJECT_KINDS_PROSE: string;
+/** Inline label for a count: `collabSubjectLabel("sequence", 1)` -> "sequence". */
+export declare function collabSubjectLabel(kind: string, count: number): string;
+/** Section heading for a kind: "Sequences", "CRM records". */
+export declare function collabSubjectHeading(kind: string): string;
+/** A thread's or request's subject: which kind of object, and which one. */
+export type CollabSubjectRef = {
+    kind: CollabSubjectKind;
+    id: string;
+};
+/**
+ * Render a subject as the `<kind>:<id>` string every surface accepts
+ * (`--on sequence:9f1c...`). Throws rather than emitting an unparseable ref,
+ * because a malformed ref written into a stored row is drift nobody notices
+ * until a read fails.
+ */
+export declare function formatSubjectRef(ref: CollabSubjectRef): string;
+/**
+ * Parse `<kind>:<id>`. Splits on the FIRST colon only, so an id that itself
+ * contains colons survives the round trip; an input with no colon at all is
+ * rejected rather than being guessed at (there is no default kind — a bare id
+ * would silently address the wrong store).
+ */
+export declare function tryParseSubjectRef(value: unknown): CollabSubjectRef | null;
+/** Throwing variant of {@link tryParseSubjectRef}, for surfaces that want the typed error. */
+export declare function parseSubjectRef(value: unknown): CollabSubjectRef;
+/**
+ * Sub-object addressing inside one subject, so commenting on a single cell does
+ * not need a thread table per kind: `row:<rowId>` for a whole row,
+ * `row:<rowId>#<columnKey>` for one cell, `column:<columnKey>` for a whole
+ * column. Unknown prefixes are still rejected rather than stored — an address no
+ * reader understands is worse than a refusal.
+ *
+ * `column:` was added in the second Collaboration pass because a column is what
+ * an agency and its client actually argue about ("why is Stage set this way?"),
+ * and it had no address at all: every path had to name a row first. It is a
+ * SIBLING of `row:`, not a variant of it, which is why the type below is a
+ * discriminated union — a column path has no row, and an optional `rowId` would
+ * let `{}` typecheck as a valid path.
+ */
+export declare const SUBJECT_PATH_ROW_PREFIX = "row:";
+export declare const SUBJECT_PATH_COLUMN_PREFIX = "column:";
+export type CollabSubjectPath = {
+    kind: "row";
+    rowId: string;
+    columnKey?: string;
+} | {
+    kind: "column";
+    columnKey: string;
+};
+/** Every path form in prose, for `--help`, MCP descriptors, and error messages. */
+export declare const SUBJECT_PATH_FORMS_PROSE = "\"row:<rowId>\" for one row, \"row:<rowId>#<columnKey>\" for one cell, or \"column:<columnKey>\" for one column";
+/**
+ * Render a sub-object path: `{ kind: "row", rowId: "abc" }` -> "row:abc"; with a
+ * column -> "row:abc#email"; `{ kind: "column", columnKey: "email" }` ->
+ * "column:email".
+ */
+export declare function formatSubjectPath(path: CollabSubjectPath): string;
+export declare function tryParseSubjectPath(value: unknown): CollabSubjectPath | null;
+/** Throwing variant of {@link tryParseSubjectPath}. */
+export declare function parseSubjectPath(value: unknown): CollabSubjectPath;
+/**
+ * The gates a workspace can require. `launch` is the client's go/no-go before a
+ * campaign sends; `signoff` is their sign-off on the list that campaign sends
+ * to. Both are OPT-IN per subject (or per subject kind) — an unset gate leaves
+ * today's behavior untouched.
+ */
+export declare const COLLAB_GATE_KINDS: readonly ["launch", "signoff"];
+export type CollabGateKind = (typeof COLLAB_GATE_KINDS)[number];
+export declare function isCollabGateKind(value: unknown): value is CollabGateKind;
+/**
+ * Which subject kinds each gate can be required on. Total over CollabGateKind,
+ * so a new gate cannot ship without naming the primitives that must honor it —
+ * a gate nobody enforces is worse than no gate, because the workspace believes
+ * it is protected.
+ */
+export declare const GATE_KIND_SUBJECTS: Record<CollabGateKind, readonly CollabSubjectKind[]>;
+/** What each gate means, for `--help` and MCP descriptors. Total over CollabGateKind. */
+export declare const COLLAB_GATE_PROSE: Record<CollabGateKind, string>;
+export declare function isGateKindValidForSubject(gateKind: unknown, subjectKind: unknown): gateKind is CollabGateKind;
+/** Every gate that can be required on a subject kind — drives `approvals gate list`. */
+export declare function gateKindsForSubject(subjectKind: unknown): CollabGateKind[];
+/** A thread is open until somebody resolves it; reopening flips it back. */
+export declare const COLLAB_THREAD_STATUSES: readonly ["open", "resolved"];
+export type CollabThreadStatus = (typeof COLLAB_THREAD_STATUSES)[number];
+export declare function isCollabThreadStatus(value: unknown): value is CollabThreadStatus;
+export declare const COLLAB_REQUEST_STATUSES: readonly ["pending", "approved", "changes_requested", "rejected", "cancelled", "expired"];
+export type CollabRequestStatus = (typeof COLLAB_REQUEST_STATUSES)[number];
+export declare function isCollabRequestStatus(value: unknown): value is CollabRequestStatus;
+/**
+ * The whole feature hinges on this one line: ONLY `approved` opens a gate.
+ *
+ * `changes_requested` is a decision, and it ends the requester's wait, but it is
+ * not consent — the client asked for edits. Treating it as terminal-and-done is
+ * the obvious bug (a request that is no longer pending looks "handled"), so the
+ * gate check asks this function rather than testing `status !== "pending"`.
+ */
+export declare function requestStatusOpensGate(status: unknown): boolean;
+/** Statuses that no longer await a decision. `pending` is the only live state. */
+export declare const COLLAB_REQUEST_TERMINAL_STATUSES: readonly CollabRequestStatus[];
+export declare function isTerminalRequestStatus(status: unknown): boolean;
+/**
+ * What an approver may do, as the CLI/MCP spells it — and the status each
+ * decision writes. Total over CollabDecision so the API, the CLI flags, and the
+ * MCP tool cannot each invent their own mapping (the failure mode being a
+ * `changes_requested` decision stored as `rejected`, which reads to the agency
+ * as "the client said no" rather than "the client wants edits").
+ */
+export declare const COLLAB_DECISIONS: readonly ["approve", "reject", "changes_requested"];
+export type CollabDecision = (typeof COLLAB_DECISIONS)[number];
+export declare function isCollabDecision(value: unknown): value is CollabDecision;
+export declare const COLLAB_DECISION_STATUSES: Record<CollabDecision, CollabRequestStatus>;
+/** Why a notification exists. Delivery itself is the notifier's problem. */
+export declare const COLLAB_NOTIFICATION_KINDS: readonly ["assigned", "mentioned", "decided", "replied"];
+export type CollabNotificationKind = (typeof COLLAB_NOTIFICATION_KINDS)[number];
+export declare function isCollabNotificationKind(value: unknown): value is CollabNotificationKind;
+export declare const COLLAB_NOTIFICATION_STATUSES: readonly ["pending", "sent", "failed", "skipped"];
+export type CollabNotificationStatus = (typeof COLLAB_NOTIFICATION_STATUSES)[number];
+export declare function isCollabNotificationStatus(value: unknown): value is CollabNotificationStatus;
+/**
+ * Body/field caps. Shared so the API, the CLI, and the tenant column widths
+ * agree — three independently chosen limits means the CLI accepts what the API
+ * truncates.
+ */
+export declare const MAX_COMMENT_BODY_LENGTH = 10000;
+export declare const MAX_THREAD_TITLE_LENGTH = 200;
+export declare const MAX_DECISION_NOTE_LENGTH = 2000;
+/** Bounds the notification fan-out one comment or request can trigger. */
+export declare const MAX_MENTIONS_PER_COMMENT = 25;
+export declare const MAX_ASSIGNEES_PER_REQUEST = 10;
+/**
+ * Normalize one comment body: trim, reject blanks, non-strings, and anything
+ * over {@link MAX_COMMENT_BODY_LENGTH}. Returns `null` so each surface can raise
+ * its own typed error (the CLI wants an exit code, the API wants a status).
+ *
+ * Deliberately does NOT strip or rewrite the body beyond trimming — a comment is
+ * the client's words, and Markdown, quoted text, and whitespace layout are part
+ * of what they wrote.
+ */
+export declare function normalizeCommentBody(value: unknown): string | null;
+/**
+ * The Oxygen-side membership role overlay (control DB
+ * `organization_memberships.oxygen_role`). NULL means no override — today's
+ * behavior for every existing member — and `client` is the restricted role an
+ * agency hands its client: read the work, comment on it, decide the approvals
+ * assigned to them, and nothing else.
+ *
+ * Deliberately not a Clerk custom role: those need dashboard configuration, and
+ * repo doctrine requires asking a human before touching Clerk. Keep this list in
+ * step with the `organization_memberships_oxygen_role_check` constraint in
+ * control migration 0095 — the CHECK is what stops a typo from creating a role
+ * nothing enforces.
+ */
+export declare const COLLAB_MEMBER_ROLES: readonly ["client"];
+export type CollabMemberRole = (typeof COLLAB_MEMBER_ROLES)[number];
+export declare function isCollabMemberRole(value: unknown): value is CollabMemberRole;
+/**
+ * The CLERK workspace roles that carry admin authority (control DB
+ * `organization_memberships.role`). Both spellings of each: Clerk writes the
+ * `org:`-prefixed form, older rows carry the bare one.
+ *
+ * The overlay above and this list are the two halves of one question — "may this
+ * member do X" — and a Clerk admin's role OVERRIDES the overlay, which is why
+ * granting `client` to one is refused. Keeping the vocabulary here means the
+ * collaboration lib can ask without importing the billing graph, and there is
+ * one list to change if Clerk ever gains another admin-ish role.
+ */
+export declare const WORKSPACE_ADMIN_ROLES: readonly ["admin", "owner", "org:admin", "org:owner"];
+export declare function isWorkspaceAdminRole(role: string): boolean;
+export {};

package/node_modules/@oxygen/shared/dist/collab.js

@@ -0,0 +1,417 @@
+// Collaboration vocabulary (Control-layer interaction state, NOT a sixteenth
+// primitive). A comment thread or an approval request is state ABOUT a GTM
+// artifact — the artifact itself still belongs to its owning primitive, and the
+// approval gate is honored by that primitive's own route (Sequences still owns
+// whether a sequence launches). Same precedent ADR 0013 set for the Workspace
+// Copilot: durable interaction state may own a tenant store, GTM primitive
+// state may not.
+//
+// This module is the ONE vocabulary the tenant schema (`ox_collab`), the
+// `/api/cli/collab/*` routes, the CLI groups, and the MCP tools all read from:
+// which kinds can carry a thread, how a subject is addressed as a string, which
+// gates apply to which kinds, and what the statuses are. Nothing here talks to a
+// database or a transport — it is deliberately importable from every surface.
+//
+// Unlike Tags (a label that fits in a `text[]` column on the row it describes),
+// a thread is an independent entity with its own author, body, replies, and
+// lifecycle, so it is stored separately and addressed by an explicit subject
+// reference — `<kind>:<id>` — rather than by a column on the subject.
+import { OxygenError } from "./cli-result.js";
+/**
+ * Workspace objects that can carry a comment thread or an approval request.
+ *
+ * Seeded from {@link TAG_KINDS}: anything worth labelling for a campaign is
+ * worth discussing with the client who signs that campaign off. The list is
+ * RESTATED rather than aliased because it is also a stored value — existing
+ * `ox_collab` rows pin it — so widening the tag vocabulary must be a deliberate
+ * decision here, not a silent side effect. (`subject_kind` deliberately carries
+ * no enum CHECK; 0182_collab.sql explains why, so adding a kind here needs no
+ * tenant migration.) The alignment is enforced
+ * both ways: {@link EveryTagKindIsCommentable} fails the build if a taggable
+ * kind is missing, and the paired test pins today's list exactly.
+ */
+export const COLLAB_SUBJECT_KINDS = [
+    "knowledge_page",
+    "publishing_post",
+    "sequence",
+    "table",
+    "workflow",
+    "recipe",
+    "conversation",
+    "mailbox",
+    "sender",
+    "record",
+    "domain",
+    "project",
+    "sender_profile",
+    "voice_number",
+];
+export function isCollabSubjectKind(value) {
+    return typeof value === "string" && COLLAB_SUBJECT_KINDS.includes(value);
+}
+/**
+ * How each subject kind is named in output. Total over CollabSubjectKind, so
+ * adding a kind is a compile error until it is labelled — the guarantee
+ * `TAG_KIND_LABELS` had to learn the hard way when three hand-maintained copies
+ * of the same map drifted apart.
+ *
+ * `many` keeps proper nouns intact ("CRM records") so an inline count reads
+ * correctly; headings run it through {@link collabSubjectHeading}, which only
+ * uppercases a leading lowercase letter.
+ */
+export const COLLAB_SUBJECT_LABELS = {
+    knowledge_page: { one: "knowledge page", many: "knowledge pages" },
+    publishing_post: { one: "publishing post", many: "publishing posts" },
+    sequence: { one: "sequence", many: "sequences" },
+    table: { one: "table", many: "tables" },
+    workflow: { one: "workflow", many: "workflows" },
+    recipe: { one: "recipe", many: "recipes" },
+    conversation: { one: "conversation", many: "conversations" },
+    mailbox: { one: "mailbox", many: "mailboxes" },
+    sender: { one: "sender account", many: "sender accounts" },
+    record: { one: "CRM record", many: "CRM records" },
+    domain: { one: "sending domain", many: "sending domains" },
+    project: { one: "project", many: "projects" },
+    sender_profile: { one: "sender profile", many: "sender profiles" },
+    voice_number: { one: "phone number", many: "phone numbers" },
+};
+/**
+ * What a thread on each kind is usually about, for `--help` and MCP tool
+ * descriptions. Total over CollabSubjectKind for the same reason the labels
+ * are: a blind-user eval (2026-07-21) found `tags --help` still advertising 7
+ * of 13 kinds because the prose was hand-written beside a hand-maintained
+ * marker map, so six taggable kinds were invisible from the one place a user
+ * looks. Here the help text cannot omit a kind — the compiler rejects the map
+ * until the kind is glossed, and {@link COLLAB_SUBJECT_KINDS_PROSE} is DERIVED
+ * from the labels rather than typed out a second time.
+ */
+export const COLLAB_SUBJECT_PROSE = {
+    knowledge_page: "a wiki page's copy before it becomes canonical",
+    publishing_post: "a post's copy before it is published",
+    sequence: "a campaign's messaging before it launches",
+    table: "a list's rows and columns, or one cell's value",
+    workflow: "an automation's graph before it runs live",
+    recipe: "an installable motion before it is installed",
+    conversation: "a reply in an inbox thread before it is sent",
+    mailbox: "a mailbox's configuration or health",
+    sender: "a sender account's caps and warmup",
+    record: "a CRM record's truth",
+    domain: "a sending domain's DNS and warmup",
+    project: "a project's scope",
+    sender_profile: "a sending identity's accounts and inboxes",
+    voice_number: "a dialing number's caps and warmup",
+};
+/** Oxford-comma list: ["a"] -> "a"; ["a","b"] -> "a and b"; ["a","b","c"] -> "a, b, and c". */
+function formatProseList(items) {
+    if (items.length <= 1)
+        return items[0] ?? "";
+    if (items.length === 2)
+        return `${items[0]} and ${items[1]}`;
+    return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+/**
+ * Every commentable kind in prose, for CLI `--help` and MCP tool descriptions.
+ * Derived from {@link COLLAB_SUBJECT_LABELS} on purpose: a hand-written copy is
+ * exactly what drifted in the tags help.
+ */
+export const COLLAB_SUBJECT_KINDS_PROSE = formatProseList(COLLAB_SUBJECT_KINDS.map((kind) => COLLAB_SUBJECT_LABELS[kind].many));
+/** Inline label for a count: `collabSubjectLabel("sequence", 1)` -> "sequence". */
+export function collabSubjectLabel(kind, count) {
+    const entry = isCollabSubjectKind(kind) ? COLLAB_SUBJECT_LABELS[kind] : null;
+    if (!entry)
+        return kind;
+    return count === 1 ? entry.one : entry.many;
+}
+/** Section heading for a kind: "Sequences", "CRM records". */
+export function collabSubjectHeading(kind) {
+    const entry = isCollabSubjectKind(kind) ? COLLAB_SUBJECT_LABELS[kind] : null;
+    const label = entry ? entry.many : kind;
+    return label.charAt(0).toUpperCase() + label.slice(1);
+}
+/**
+ * Render a subject as the `<kind>:<id>` string every surface accepts
+ * (`--on sequence:9f1c...`). Throws rather than emitting an unparseable ref,
+ * because a malformed ref written into a stored row is drift nobody notices
+ * until a read fails.
+ */
+export function formatSubjectRef(ref) {
+    if (!isCollabSubjectKind(ref.kind)) {
+        throw invalidSubjectRef(`Unknown subject kind "${ref.kind}".`, { kind: ref.kind });
+    }
+    const id = ref.id.trim();
+    if (!id) {
+        throw invalidSubjectRef("Subject id is required.", { kind: ref.kind });
+    }
+    return `${ref.kind}:${id}`;
+}
+/**
+ * Parse `<kind>:<id>`. Splits on the FIRST colon only, so an id that itself
+ * contains colons survives the round trip; an input with no colon at all is
+ * rejected rather than being guessed at (there is no default kind — a bare id
+ * would silently address the wrong store).
+ */
+export function tryParseSubjectRef(value) {
+    if (typeof value !== "string")
+        return null;
+    const raw = value.trim();
+    const separator = raw.indexOf(":");
+    if (separator <= 0)
+        return null;
+    const kind = raw.slice(0, separator);
+    const id = raw.slice(separator + 1).trim();
+    if (!isCollabSubjectKind(kind) || !id)
+        return null;
+    return { kind, id };
+}
+/** Throwing variant of {@link tryParseSubjectRef}, for surfaces that want the typed error. */
+export function parseSubjectRef(value) {
+    const parsed = tryParseSubjectRef(value);
+    if (parsed)
+        return parsed;
+    throw invalidSubjectRef(`Subject must be "<kind>:<id>" — for example "sequence:9f1c2b7e". Valid kinds: ${COLLAB_SUBJECT_KINDS.join(", ")}.`, { subject: typeof value === "string" ? value : null });
+}
+function invalidSubjectRef(message, details) {
+    return new OxygenError("invalid_subject_ref", message, {
+        details: { ...details, valid_kinds: [...COLLAB_SUBJECT_KINDS] },
+        exitCode: 2,
+    });
+}
+/**
+ * Sub-object addressing inside one subject, so commenting on a single cell does
+ * not need a thread table per kind: `row:<rowId>` for a whole row,
+ * `row:<rowId>#<columnKey>` for one cell, `column:<columnKey>` for a whole
+ * column. Unknown prefixes are still rejected rather than stored — an address no
+ * reader understands is worse than a refusal.
+ *
+ * `column:` was added in the second Collaboration pass because a column is what
+ * an agency and its client actually argue about ("why is Stage set this way?"),
+ * and it had no address at all: every path had to name a row first. It is a
+ * SIBLING of `row:`, not a variant of it, which is why the type below is a
+ * discriminated union — a column path has no row, and an optional `rowId` would
+ * let `{}` typecheck as a valid path.
+ */
+export const SUBJECT_PATH_ROW_PREFIX = "row:";
+export const SUBJECT_PATH_COLUMN_PREFIX = "column:";
+/** Every path form in prose, for `--help`, MCP descriptors, and error messages. */
+export const SUBJECT_PATH_FORMS_PROSE = '"row:<rowId>" for one row, "row:<rowId>#<columnKey>" for one cell, or "column:<columnKey>" for one column';
+/**
+ * Render a sub-object path: `{ kind: "row", rowId: "abc" }` -> "row:abc"; with a
+ * column -> "row:abc#email"; `{ kind: "column", columnKey: "email" }` ->
+ * "column:email".
+ */
+export function formatSubjectPath(path) {
+    if (path.kind === "column") {
+        const columnKey = path.columnKey.trim();
+        if (!columnKey || columnKey.includes("#")) {
+            throw invalidSubjectPath('Column key is required and cannot contain "#".', {
+                column_key: path.columnKey,
+            });
+        }
+        return `${SUBJECT_PATH_COLUMN_PREFIX}${columnKey}`;
+    }
+    const rowId = path.rowId.trim();
+    if (!rowId || rowId.includes("#")) {
+        throw invalidSubjectPath('Row id is required and cannot contain "#".', { row_id: path.rowId });
+    }
+    const columnKey = path.columnKey?.trim() ?? "";
+    if (path.columnKey !== undefined && !columnKey) {
+        throw invalidSubjectPath("Column key cannot be blank.", { row_id: rowId });
+    }
+    const base = `${SUBJECT_PATH_ROW_PREFIX}${rowId}`;
+    return columnKey ? `${base}#${columnKey}` : base;
+}
+export function tryParseSubjectPath(value) {
+    if (typeof value !== "string")
+        return null;
+    const raw = value.trim();
+    if (raw.startsWith(SUBJECT_PATH_COLUMN_PREFIX)) {
+        const columnKey = raw.slice(SUBJECT_PATH_COLUMN_PREFIX.length).trim();
+        // No `#` inside a column path: a column addresses no row, so a hash here
+        // means the caller meant a cell and got the prefix wrong.
+        if (!columnKey || columnKey.includes("#"))
+            return null;
+        return { kind: "column", columnKey };
+    }
+    if (!raw.startsWith(SUBJECT_PATH_ROW_PREFIX))
+        return null;
+    const remainder = raw.slice(SUBJECT_PATH_ROW_PREFIX.length);
+    const hash = remainder.indexOf("#");
+    if (hash < 0) {
+        const rowId = remainder.trim();
+        return rowId ? { kind: "row", rowId } : null;
+    }
+    const rowId = remainder.slice(0, hash).trim();
+    const columnKey = remainder.slice(hash + 1).trim();
+    if (!rowId || !columnKey || columnKey.includes("#"))
+        return null;
+    return { kind: "row", rowId, columnKey };
+}
+/** Throwing variant of {@link tryParseSubjectPath}. */
+export function parseSubjectPath(value) {
+    const parsed = tryParseSubjectPath(value);
+    if (parsed)
+        return parsed;
+    throw invalidSubjectPath(`Path must be ${SUBJECT_PATH_FORMS_PROSE} — for example "row:8f2c1a4d#email".`, { path: typeof value === "string" ? value : null });
+}
+function invalidSubjectPath(message, details) {
+    return new OxygenError("invalid_subject_path", message, { details, exitCode: 2 });
+}
+/**
+ * The gates a workspace can require. `launch` is the client's go/no-go before a
+ * campaign sends; `signoff` is their sign-off on the list that campaign sends
+ * to. Both are OPT-IN per subject (or per subject kind) — an unset gate leaves
+ * today's behavior untouched.
+ */
+export const COLLAB_GATE_KINDS = ["launch", "signoff"];
+export function isCollabGateKind(value) {
+    return typeof value === "string" && COLLAB_GATE_KINDS.includes(value);
+}
+/**
+ * Which subject kinds each gate can be required on. Total over CollabGateKind,
+ * so a new gate cannot ship without naming the primitives that must honor it —
+ * a gate nobody enforces is worse than no gate, because the workspace believes
+ * it is protected.
+ */
+export const GATE_KIND_SUBJECTS = {
+    launch: ["sequence"],
+    signoff: ["table"],
+};
+/** What each gate means, for `--help` and MCP descriptors. Total over CollabGateKind. */
+export const COLLAB_GATE_PROSE = {
+    launch: "approve before a sequence starts sending live",
+    signoff: "approve the table's rows before they are worked",
+};
+export function isGateKindValidForSubject(gateKind, subjectKind) {
+    if (!isCollabGateKind(gateKind) || !isCollabSubjectKind(subjectKind))
+        return false;
+    return GATE_KIND_SUBJECTS[gateKind].includes(subjectKind);
+}
+/** Every gate that can be required on a subject kind — drives `approvals gate list`. */
+export function gateKindsForSubject(subjectKind) {
+    if (!isCollabSubjectKind(subjectKind))
+        return [];
+    return COLLAB_GATE_KINDS.filter((gate) => GATE_KIND_SUBJECTS[gate].includes(subjectKind));
+}
+/** A thread is open until somebody resolves it; reopening flips it back. */
+export const COLLAB_THREAD_STATUSES = ["open", "resolved"];
+export function isCollabThreadStatus(value) {
+    return typeof value === "string" && COLLAB_THREAD_STATUSES.includes(value);
+}
+export const COLLAB_REQUEST_STATUSES = [
+    "pending",
+    "approved",
+    "changes_requested",
+    "rejected",
+    "cancelled",
+    "expired",
+];
+export function isCollabRequestStatus(value) {
+    return typeof value === "string" && COLLAB_REQUEST_STATUSES.includes(value);
+}
+/**
+ * The whole feature hinges on this one line: ONLY `approved` opens a gate.
+ *
+ * `changes_requested` is a decision, and it ends the requester's wait, but it is
+ * not consent — the client asked for edits. Treating it as terminal-and-done is
+ * the obvious bug (a request that is no longer pending looks "handled"), so the
+ * gate check asks this function rather than testing `status !== "pending"`.
+ */
+export function requestStatusOpensGate(status) {
+    return status === "approved";
+}
+/** Statuses that no longer await a decision. `pending` is the only live state. */
+export const COLLAB_REQUEST_TERMINAL_STATUSES = [
+    "approved",
+    "changes_requested",
+    "rejected",
+    "cancelled",
+    "expired",
+];
+export function isTerminalRequestStatus(status) {
+    return isCollabRequestStatus(status) && status !== "pending";
+}
+/**
+ * What an approver may do, as the CLI/MCP spells it — and the status each
+ * decision writes. Total over CollabDecision so the API, the CLI flags, and the
+ * MCP tool cannot each invent their own mapping (the failure mode being a
+ * `changes_requested` decision stored as `rejected`, which reads to the agency
+ * as "the client said no" rather than "the client wants edits").
+ */
+export const COLLAB_DECISIONS = ["approve", "reject", "changes_requested"];
+export function isCollabDecision(value) {
+    return typeof value === "string" && COLLAB_DECISIONS.includes(value);
+}
+export const COLLAB_DECISION_STATUSES = {
+    approve: "approved",
+    reject: "rejected",
+    changes_requested: "changes_requested",
+};
+/** Why a notification exists. Delivery itself is the notifier's problem. */
+export const COLLAB_NOTIFICATION_KINDS = ["assigned", "mentioned", "decided", "replied"];
+export function isCollabNotificationKind(value) {
+    return (typeof value === "string" && COLLAB_NOTIFICATION_KINDS.includes(value));
+}
+export const COLLAB_NOTIFICATION_STATUSES = ["pending", "sent", "failed", "skipped"];
+export function isCollabNotificationStatus(value) {
+    return (typeof value === "string" && COLLAB_NOTIFICATION_STATUSES.includes(value));
+}
+/**
+ * Body/field caps. Shared so the API, the CLI, and the tenant column widths
+ * agree — three independently chosen limits means the CLI accepts what the API
+ * truncates.
+ */
+export const MAX_COMMENT_BODY_LENGTH = 10_000;
+export const MAX_THREAD_TITLE_LENGTH = 200;
+export const MAX_DECISION_NOTE_LENGTH = 2_000;
+/** Bounds the notification fan-out one comment or request can trigger. */
+export const MAX_MENTIONS_PER_COMMENT = 25;
+export const MAX_ASSIGNEES_PER_REQUEST = 10;
+/**
+ * Normalize one comment body: trim, reject blanks, non-strings, and anything
+ * over {@link MAX_COMMENT_BODY_LENGTH}. Returns `null` so each surface can raise
+ * its own typed error (the CLI wants an exit code, the API wants a status).
+ *
+ * Deliberately does NOT strip or rewrite the body beyond trimming — a comment is
+ * the client's words, and Markdown, quoted text, and whitespace layout are part
+ * of what they wrote.
+ */
+export function normalizeCommentBody(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim();
+    if (!normalized || normalized.length > MAX_COMMENT_BODY_LENGTH)
+        return null;
+    return normalized;
+}
+/**
+ * The Oxygen-side membership role overlay (control DB
+ * `organization_memberships.oxygen_role`). NULL means no override — today's
+ * behavior for every existing member — and `client` is the restricted role an
+ * agency hands its client: read the work, comment on it, decide the approvals
+ * assigned to them, and nothing else.
+ *
+ * Deliberately not a Clerk custom role: those need dashboard configuration, and
+ * repo doctrine requires asking a human before touching Clerk. Keep this list in
+ * step with the `organization_memberships_oxygen_role_check` constraint in
+ * control migration 0095 — the CHECK is what stops a typo from creating a role
+ * nothing enforces.
+ */
+export const COLLAB_MEMBER_ROLES = ["client"];
+export function isCollabMemberRole(value) {
+    return typeof value === "string" && COLLAB_MEMBER_ROLES.includes(value);
+}
+/**
+ * The CLERK workspace roles that carry admin authority (control DB
+ * `organization_memberships.role`). Both spellings of each: Clerk writes the
+ * `org:`-prefixed form, older rows carry the bare one.
+ *
+ * The overlay above and this list are the two halves of one question — "may this
+ * member do X" — and a Clerk admin's role OVERRIDES the overlay, which is why
+ * granting `client` to one is refused. Keeping the vocabulary here means the
+ * collaboration lib can ask without importing the billing graph, and there is
+ * one list to change if Clerk ever gains another admin-ish role.
+ */
+export const WORKSPACE_ADMIN_ROLES = ["admin", "owner", "org:admin", "org:owner"];
+export function isWorkspaceAdminRole(role) {
+    return WORKSPACE_ADMIN_ROLES.includes(role.toLowerCase());
+}

package/node_modules/@oxygen/shared/dist/column-types.d.ts

@@ -12,8 +12,8 @@
  */
 /** Data types an import can infer for a brand-new column. Dates-only by design. */
 export type ImportColumnDataType = "text" | "timestamptz";
-/** Data types a `text` column can be explicitly retyped into. */
-export type RetypeableDataType = "text" | "numeric" | "boolean" | "timestamptz";
+/** Data types a plain data column can be explicitly retyped into. */
+export type RetypeableDataType = "text" | "numeric" | "boolean" | "jsonb" | "timestamptz";
 export declare const RETYPEABLE_DATA_TYPES: readonly RetypeableDataType[];
 export declare const EXCEL_SERIAL_MIN = 10000;
 export declare const EXCEL_SERIAL_MAX = 80000;
@@ -41,7 +41,7 @@ export declare function parseDateValueToIso(value: unknown, options?: {
 export declare function inferImportColumnDataType(label: string, values: Iterable<unknown>): ImportColumnDataType;
 export type CoercionResult = {
     ok: true;
-    value: string | number | boolean | null;
+    value: unknown | null;
 } | {
     ok: false;
     reason: string;