@oxygen-agent/cli 1.638.1 → 1.662.0

package/node_modules/@oxygen/shared/dist/axiom-field-budget.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The `oxygen-logs` field budget — one shared contract for both log shippers.
+ *
+ * WHY THIS EXISTS. Axiom caps a dataset at 1,024 distinct fields. `oxygen-logs`
+ * is shared by the Fly worker, the Vercel web runtime, and the Vercel log drain,
+ * and it reached that cap: measured 2026-08-08, **1,026 fields**. At the cap a
+ * single unrecognised key does not get dropped — Axiom rejects the ENTIRE ingest
+ * batch with HTTP 400, including every schema-stable record travelling with it.
+ *
+ * The worker already survived this, with a 400-triggered fallback that packed
+ * unknown keys into `message` and stayed there for the process lifetime. The web
+ * shipper had no such path: it logged `web.log_shipper.ingest_failed` and threw
+ * the batch away — 409 times in the 7 days to 2026-08-08, invisible to every
+ * Lane A query because the failure line could not ship itself either.
+ *
+ * So the strategy inverts. Instead of reacting to a 400, both shippers now pack
+ * PROACTIVELY: a fixed allowlist stays flat and queryable, and everything else —
+ * including every field any future code invents — is serialized into `message`
+ * under `worker_fields`. New instrumentation can then be added freely without
+ * anyone having to remember that a new key can take down log shipping globally.
+ *
+ * THE ALLOWLIST IS A LOAD-BEARING CONTRACT IN BOTH DIRECTIONS.
+ *
+ * - A field that a monitor, dashboard, or checked-in query reads **flat** must be
+ *   in this set. Removing one does not break ingestion; it silently moves the
+ *   value into `message` and the query starts returning zero, which reads as an
+ *   all-clear forever.
+ * - A field that a monitor reads **out of `worker_fields`** must NOT be here.
+ *   `[P3] OXYGEN Prod Egress order reconcile stuck` does
+ *   `extend wf = parse_json(tostring(message)).worker_fields | dcount(tostring(wf.order_ref))`
+ *   — promoting `order_ref` to a flat field would make `wf.order_ref` null and
+ *   that monitor would report zero stuck orders while orders were stuck.
+ *
+ * Both directions are asserted by `scripts/ci/log-field-budget.mjs` against the
+ * real seed and dashboard JSON, so a change to either side fails loudly instead
+ * of quietly blinding a monitor.
+ */
+/**
+ * Fields that stay top-level in `oxygen-logs`.
+ *
+ * Grouped by why each group is here. Do not add a field without a reader — the
+ * whole point of the budget is that flat columns are a scarce, spoken-for
+ * resource.
+ */
+export declare const AXIOM_STABLE_FIELDS: ReadonlySet<string>;
+/**
+ * The Axiom **map field** every non-allowlisted key is nested under.
+ *
+ * Map fields are Axiom's own answer to this problem and they are strictly better
+ * than the JSON-string packing this module shipped first: data inside a map field
+ * does not count toward the dataset field limit at all, AND it stays natively
+ * queryable with its types intact — `['worker_fields']['order_ref']`, no
+ * `parse_json(tostring(message))` wrapper, no everything-becomes-a-string.
+ *
+ * Proven on `oxygen-logs-dev` 2026-08-08: three records carrying three novel keys
+ * plus a nested object moved the dataset field count by exactly **+1** — the map
+ * field itself — where the same records as flat keys would have cost five columns.
+ *
+ * The name is deliberately unchanged from the old JSON blob's inner key, so every
+ * runbook, monitor, and memory that says "overflow lives in worker_fields" is
+ * still true; only the access path got shorter.
+ *
+ * The map field must EXIST on the dataset before ingest, or the keys land as
+ * ordinary flat fields and the budget is defeated silently. Create it with:
+ *   POST /v2/datasets/{dataset}/mapfields  {"name": "worker_fields"}
+ * `scripts/ops/axiom-mapfields.mjs` does this idempotently for every log dataset.
+ */
+export declare const AXIOM_OVERFLOW_MAP_FIELD = "worker_fields";
+/**
+ * Bound on the serialized overflow, so one pathological record cannot push a whole
+ * batch past Axiom's request limits. 64 KB is far above any real log line and far
+ * below anything that would matter.
+ */
+export declare const MAX_PACKED_MESSAGE_LENGTH: number;
+/**
+ * Splits a flat `log()` record into the allowlisted columns plus one map field
+ * holding everything else.
+ *
+ * The resulting shape is the query contract:
+ *
+ * ```kusto
+ * ['oxygen-logs']
+ * | where msg == 'worker.egress_order_reconcile_stuck'
+ * | summarize dcount(tostring(['worker_fields']['order_ref']))
+ * ```
+ *
+ * `worker_fields` keeps its name even for web records: it is already the word
+ * every existing monitor, dashboard, and runbook uses for "the overflow", and
+ * renaming it would silently zero those queries for no gain.
+ */
+export declare function packAxiomLogRecord(record: Record<string, unknown>): Record<string, unknown>;

package/node_modules/@oxygen/shared/dist/axiom-field-budget.js

@@ -0,0 +1,262 @@
+/**
+ * The `oxygen-logs` field budget — one shared contract for both log shippers.
+ *
+ * WHY THIS EXISTS. Axiom caps a dataset at 1,024 distinct fields. `oxygen-logs`
+ * is shared by the Fly worker, the Vercel web runtime, and the Vercel log drain,
+ * and it reached that cap: measured 2026-08-08, **1,026 fields**. At the cap a
+ * single unrecognised key does not get dropped — Axiom rejects the ENTIRE ingest
+ * batch with HTTP 400, including every schema-stable record travelling with it.
+ *
+ * The worker already survived this, with a 400-triggered fallback that packed
+ * unknown keys into `message` and stayed there for the process lifetime. The web
+ * shipper had no such path: it logged `web.log_shipper.ingest_failed` and threw
+ * the batch away — 409 times in the 7 days to 2026-08-08, invisible to every
+ * Lane A query because the failure line could not ship itself either.
+ *
+ * So the strategy inverts. Instead of reacting to a 400, both shippers now pack
+ * PROACTIVELY: a fixed allowlist stays flat and queryable, and everything else —
+ * including every field any future code invents — is serialized into `message`
+ * under `worker_fields`. New instrumentation can then be added freely without
+ * anyone having to remember that a new key can take down log shipping globally.
+ *
+ * THE ALLOWLIST IS A LOAD-BEARING CONTRACT IN BOTH DIRECTIONS.
+ *
+ * - A field that a monitor, dashboard, or checked-in query reads **flat** must be
+ *   in this set. Removing one does not break ingestion; it silently moves the
+ *   value into `message` and the query starts returning zero, which reads as an
+ *   all-clear forever.
+ * - A field that a monitor reads **out of `worker_fields`** must NOT be here.
+ *   `[P3] OXYGEN Prod Egress order reconcile stuck` does
+ *   `extend wf = parse_json(tostring(message)).worker_fields | dcount(tostring(wf.order_ref))`
+ *   — promoting `order_ref` to a flat field would make `wf.order_ref` null and
+ *   that monitor would report zero stuck orders while orders were stuck.
+ *
+ * Both directions are asserted by `scripts/ci/log-field-budget.mjs` against the
+ * real seed and dashboard JSON, so a change to either side fails loudly instead
+ * of quietly blinding a monitor.
+ */
+/**
+ * Fields that stay top-level in `oxygen-logs`.
+ *
+ * Grouped by why each group is here. Do not add a field without a reader — the
+ * whole point of the budget is that flat columns are a scarce, spoken-for
+ * resource.
+ */
+export const AXIOM_STABLE_FIELDS = new Set([
+    // --- Envelope stamped by log() on every record ---------------------------
+    "ts",
+    "level",
+    "msg",
+    "service_name",
+    "oxygen_version",
+    "sha",
+    "region",
+    "env",
+    "surface",
+    // --- Ambient LogContext (packages/shared/src/log.ts) ----------------------
+    // These are the correlation dimensions every query joins on. A record that
+    // loses them is debuggable only by full-text search.
+    "request_id",
+    "trace_id",
+    "org_id",
+    "organization_id",
+    "user_id",
+    "tool_name",
+    "provider",
+    "operation",
+    "tenant_database_id",
+    "run_id",
+    "chunk_id",
+    "item_id",
+    "worker_id",
+    "conversation_id",
+    // --- Error shape (errorFields) -------------------------------------------
+    "error_id",
+    "error_name",
+    "error_message",
+    "error_code",
+    // Next.js stamps `digest` on a serialized server error; it is the only value
+    // that joins a browser error report back to its `next.request_error` row.
+    "digest",
+    // --- Primitive identity --------------------------------------------------
+    "workflow_id",
+    "workflow_run_id",
+    "table_id",
+    "row_id",
+    "column_id",
+    "action_run_id",
+    "trigger_id",
+    // --- Request/route shape (web, CLI, MCP) ---------------------------------
+    // Read by `cli.command_failed`, `next.request_error`, and the MCP/CLI health
+    // dashboard, which groups failures by route and command.
+    "path",
+    "route",
+    "route_path",
+    "route_type",
+    "router_kind",
+    "method",
+    "command",
+    "latency_ms",
+    "framework_code",
+    "component",
+    // --- Outcome vocabulary --------------------------------------------------
+    "mode",
+    "status",
+    "outcome",
+    "reason",
+    "role",
+    "phase",
+    "step",
+    "dataset",
+    // --- Monitor-critical gauges ---------------------------------------------
+    // Each of these is read FLAT by a monitor in docs/observability/monitors.json.
+    // `broken_tenant_oldest_age_ms` is the value `[P1] Tenant database broken`
+    // alerts on; `pending_count` is what `[P2] tenant migration drift` minimises.
+    "broken_tenant_oldest_age_ms",
+    "pending_count",
+    "divergence",
+    "window_start",
+    // Group keys for `notifyByGroup` alerts. These are what put the offender in
+    // the notification subject — packed away, the alert still fires and names
+    // nobody, which is the whole reason those alerts were grouped.
+    "sender_account_id",
+    "stripe_event_type",
+    // --- Worker queue counters (worker cycle telemetry) ----------------------
+    "queue",
+    "ready",
+    "claimable",
+    "leased",
+    "oldest_pending_age_seconds",
+    "stalled_tenant_count",
+    "active_runs",
+    "skipped_to",
+    "ticket_reason",
+    "queue_wait_ms",
+    "ticket_age_ms",
+    "quantum_duration_ms",
+    "tenants",
+    "claimed",
+    "completed",
+    "skipped",
+    "retrying",
+    "failed",
+    "expired",
+    "finalized",
+    "repaired",
+    "chainChildrenDispatched",
+    "ingestionClaimed",
+    "ingestionCompleted",
+    "ingestionRetrying",
+    "ingestionFailed",
+    "ingestionExpired",
+    "ingestionFinalized",
+    "ingestionRepaired",
+    "workflowClaimed",
+    "workflowCompleted",
+    "workflowRetrying",
+    "workflowFailed",
+    "workflowExpired",
+    "workflowAwaitingApproval",
+    "workflowApprovalsExpired",
+    "workflowWaiting",
+    "workflowCronInitialized",
+    "workflowCronEnqueued",
+    "workflowCronFailed",
+    "linkedinPlanned",
+    "linkedinDispatched",
+    "linkedinDeferred",
+    "linkedinSkipped",
+    "linkedinFailed",
+    "publishingClaimed",
+    "publishingPublished",
+    "publishingFailed",
+    "publishingDeferred",
+    "publishingLeasesRevived",
+    "publishingLeasesFailed",
+]);
+/**
+ * The Axiom **map field** every non-allowlisted key is nested under.
+ *
+ * Map fields are Axiom's own answer to this problem and they are strictly better
+ * than the JSON-string packing this module shipped first: data inside a map field
+ * does not count toward the dataset field limit at all, AND it stays natively
+ * queryable with its types intact — `['worker_fields']['order_ref']`, no
+ * `parse_json(tostring(message))` wrapper, no everything-becomes-a-string.
+ *
+ * Proven on `oxygen-logs-dev` 2026-08-08: three records carrying three novel keys
+ * plus a nested object moved the dataset field count by exactly **+1** — the map
+ * field itself — where the same records as flat keys would have cost five columns.
+ *
+ * The name is deliberately unchanged from the old JSON blob's inner key, so every
+ * runbook, monitor, and memory that says "overflow lives in worker_fields" is
+ * still true; only the access path got shorter.
+ *
+ * The map field must EXIST on the dataset before ingest, or the keys land as
+ * ordinary flat fields and the budget is defeated silently. Create it with:
+ *   POST /v2/datasets/{dataset}/mapfields  {"name": "worker_fields"}
+ * `scripts/ops/axiom-mapfields.mjs` does this idempotently for every log dataset.
+ */
+export const AXIOM_OVERFLOW_MAP_FIELD = "worker_fields";
+/**
+ * Bound on the serialized overflow, so one pathological record cannot push a whole
+ * batch past Axiom's request limits. 64 KB is far above any real log line and far
+ * below anything that would matter.
+ */
+export const MAX_PACKED_MESSAGE_LENGTH = 64 * 1024;
+/**
+ * Splits a flat `log()` record into the allowlisted columns plus one map field
+ * holding everything else.
+ *
+ * The resulting shape is the query contract:
+ *
+ * ```kusto
+ * ['oxygen-logs']
+ * | where msg == 'worker.egress_order_reconcile_stuck'
+ * | summarize dcount(tostring(['worker_fields']['order_ref']))
+ * ```
+ *
+ * `worker_fields` keeps its name even for web records: it is already the word
+ * every existing monitor, dashboard, and runbook uses for "the overflow", and
+ * renaming it would silently zero those queries for no gain.
+ */
+export function packAxiomLogRecord(record) {
+    const stable = {};
+    const overflow = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (AXIOM_STABLE_FIELDS.has(key))
+            stable[key] = value;
+        else
+            overflow[key] = value;
+    }
+    // The capped dataset predates the Copilot column names, so `turn_id` and
+    // `session_id` cannot become flat fields. Copy them into the semantically
+    // equivalent correlation columns that DO exist — a Langfuse trace id is the
+    // turn id, and a Copilot session is the conversation grouping its turns —
+    // while leaving the exact original names inside the packed blob.
+    const copilotTraceId = record.turn_id ?? record.langfuse_trace_id;
+    if (stable.trace_id === undefined &&
+        typeof copilotTraceId === "string" &&
+        copilotTraceId.length > 0) {
+        stable.trace_id = copilotTraceId;
+    }
+    if (stable.conversation_id === undefined &&
+        typeof record.session_id === "string" &&
+        record.session_id.length > 0) {
+        stable.conversation_id = record.session_id;
+    }
+    if (Object.keys(overflow).length === 0)
+        return stable;
+    // Nested under the map field as a real object — NOT stringified. Axiom stores
+    // map contents without allocating a column per key, and keeps them queryable
+    // and typed.
+    stable[AXIOM_OVERFLOW_MAP_FIELD] =
+        JSON.stringify(overflow).length <= MAX_PACKED_MESSAGE_LENGTH
+            ? overflow
+            : {
+                // Never silently truncate to nothing: the key NAMES alone are usually
+                // enough to identify which call site produced the oversized record.
+                _truncated: true,
+                _keys: Object.keys(overflow),
+            };
+    return stable;
+}

package/node_modules/@oxygen/shared/dist/capability-discovery.js

@@ -87,6 +87,42 @@ export const OXYGEN_CAPABILITY_ROUTES = [
         endpointSections: ["admin", "db", "worker"],
         intentTerms: ["admin", "worker", "queue", "tenant repair", "database", "db status", "stuck jobs", "operations"],
     },
+    {
+        // Control-layer interaction state, deliberately NOT a sixteenth primitive
+        // (ADR 0020): a comment or an approval request is state ABOUT a GTM
+        // artifact, and the hard gate is honored by the owning primitive's own
+        // route. `primitive: null` is what keeps the fifteen-primitive assertion
+        // in OXYGEN_PRIMITIVE_ROUTES true.
+        id: "collaboration",
+        layer: "Control",
+        primitive: null,
+        owns: "Threaded internal comments on any workspace object, second-party approval requests, the opt-in gate that blocks a live action until approved, and the restricted client role.",
+        notFor: "Public comments on a published post (Posts/Publishing), the artifact itself, or a run's own approval card — those belong to their owning primitive.",
+        execution: "Comment or request a decision on a subject reference (`<kind>:<id>`); an admin arms the gate, and the owning primitive refuses its live path until an approval lands.",
+        posture: "workspace_write",
+        gatewayTools: ["oxygen_approvals_inbox", "oxygen_approvals_request", "oxygen_approvals_decide", "oxygen_comments_add", "oxygen_comments_list", "oxygen_approvals_gate_set"],
+        gatewayCommands: ["approvals inbox", "approvals request", "approvals decide", "comments add", "comments list", "approvals gate set"],
+        skills: ["oxygen-collaboration"],
+        endpointSections: ["collab"],
+        intentTerms: [
+            "collaboration",
+            "comment thread",
+            "internal comment",
+            "leave a comment",
+            "sign off",
+            "signoff",
+            "approval request",
+            "request approval",
+            "approval gate",
+            "client approval",
+            "client review",
+            "client login",
+            "client role",
+            "go no go",
+            "waiting on me",
+        ],
+        negativeTerms: ["public comment", "linkedin comment", "post comment"],
+    },
     {
         id: "agency-directory",
         layer: "Control",
@@ -475,6 +511,16 @@ function explicitCapabilityIntent(query) {
         return ROUTE_BY_PRIMITIVE.get("workflows") ?? null;
     if (isOwnedPostCommentIntent(query))
         return ROUTE_BY_PRIMITIVE.get("posts") ?? null;
+    // Asking a second party to decide is Collaboration even when the thing being
+    // decided is a campaign, a table, or a post — the subject noun would
+    // otherwise win outright ("campaign" is an explicit Sequences intent below,
+    // and that is right for every ask that is not about the decision itself).
+    // Deliberately narrow: bare "approve"/"approval" stays with the owning
+    // primitive (a publishing approval, an Observability approval queue), and
+    // this sits after the owned-post-comment check so a PUBLIC comment on a
+    // published post still routes to Posts.
+    if (isSecondPartyDecisionIntent(query))
+        return ROUTE_BY_ID.get("collaboration") ?? null;
     // A deferred acquisition motion starts with the public-data owner. This keeps
     // "find/qualify now, contact later" from skipping straight to the final write
     // step; the recommendation still hands the eventual initiation to Sequences.
@@ -743,6 +789,15 @@ function isNetNewLinkedInInitiation(query) {
         return false;
     return !/\b(sequence|campaign|cadence|enroll|nurture|multi[ -]step|multi[ -]recipient|leads|contacts|recipients|audience|rotate senders?|stop on reply|day\s*\d+)\b/.test(query);
 }
+function isSecondPartyDecisionIntent(query) {
+    const decisionLanguage = /\b(sign ?off|signoff|approval request|request approval|approval gate|go no go)\b/.test(query);
+    const clientDecision = /\bclient\b.{0,20}\b(approv\w*|sign ?off|review|decide|decision|login|role)\b/.test(query)
+        || /\b(approv\w*|sign ?off|decision)\b.{0,20}\bfrom the client\b/.test(query);
+    const internalThread = /\b(comment|comments|thread)\b/.test(query)
+        && /\b(internal|client|teammate|workspace member|discuss)\b/.test(query)
+        && !/\b(linkedin|public|published|post|posts|publishing)\b/.test(query);
+    return decisionLanguage || clientDecision || internalThread;
+}
 function isOwnedPostCommentIntent(query) {
     if (!/\bcomments?\b/.test(query) || !/\b(linkedin|posts?|publishing)\b/.test(query))
         return false;

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

@@ -0,0 +1,228 @@
+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 — the
+ * `ox_collab` CHECK constraint and existing rows pin it — so widening the tag
+ * vocabulary must be a deliberate decision here, not a silent side effect that
+ * lets the API accept a kind the database rejects. 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"];
+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 {};