runline 0.32.0 → 0.34.0

package/dist/plugins/shiftBwm/src/collections.js

@@ -0,0 +1,201 @@
+import * as t from "typebox";
+import { call, clientFor, filtersSchema, idempotentClientFor, idOrIds, idSchema, objectTypeSchema, paginationFields, principalSchema, relationshipChangeSchema, STRICT_OBJECT, STRICT_UPDATE_OBJECT, withConflictRetry, } from "./shared.js";
+// ─── saved lists ─────────────────────────────────────────────────
+export function registerSavedListActions(rl) {
+    rl.registerAction("savedList.list", {
+        access: "read",
+        description: "Saved lists: curated sets of records of one object type. Each is { id, fields: { $name, $objectType, $description }, relationships: { $records: { values: [ids] } }, createdAt, updatedAt, archivedAt }.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            return call(() => clientFor(ctx).listLists());
+        },
+    });
+    rl.registerAction("savedList.get", {
+        access: "read",
+        description: "Read one saved list envelope by id.",
+        inputSchema: t.Object({ id: idSchema("Saved list ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            return call(() => clientFor(ctx).getList(id));
+        },
+    });
+    rl.registerAction("savedList.create", {
+        access: "write",
+        description: "Create a saved list of one object type, optionally seeded with record ids. Returns the list envelope.",
+        inputSchema: t.Object({
+            name: t.String({ minLength: 1, maxLength: 200 }),
+            objectType: objectTypeSchema(),
+            description: t.Optional(t.String({ maxLength: 2_000 })),
+            records: t.Optional(idOrIds),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { name, objectType, description, records } = input;
+            const body = {
+                fields: {
+                    $name: name,
+                    $objectType: objectType,
+                    $description: description,
+                },
+                relationships: records === undefined ? {} : { $records: records },
+            };
+            return call(() => idempotentClientFor(ctx).createList(body));
+        },
+    });
+    rl.registerAction("savedList.update", {
+        access: "write",
+        description: "Rename a list, change its description, add/remove/replace its records, or archive/restore it. records takes { add, remove, replace } or a bare id / id array as replace. Lost races retry once.",
+        inputSchema: t.Object({
+            id: idSchema("Saved list ID"),
+            name: t.Optional(t.String({ minLength: 1, maxLength: 200 })),
+            description: t.Optional(t.Union([t.String({ maxLength: 2_000 }), t.Null()])),
+            records: t.Optional(relationshipChangeSchema),
+            archived: t.Optional(t.Boolean()),
+        }, STRICT_UPDATE_OBJECT),
+        async execute(input, ctx) {
+            const { id, name, description, records, archived } = input;
+            const body = {};
+            if (name !== undefined || description !== undefined) {
+                body.fields = {};
+                if (name !== undefined)
+                    body.fields.$name = name;
+                if (description !== undefined)
+                    body.fields.$description = description;
+            }
+            if (records !== undefined)
+                body.relationships = { $records: records };
+            if (archived !== undefined)
+                body.archived = archived;
+            return call(() => withConflictRetry(() => clientFor(ctx).updateList(id, body)));
+        },
+    });
+    rl.registerAction("savedList.records", {
+        access: "read",
+        description: "The members of a saved list as record envelopes: { data, object: 'list', totalCount }. Accepts the same filters and pagination as record.list.",
+        inputSchema: t.Object({
+            id: idSchema("Saved list ID"),
+            filters: t.Optional(filtersSchema()),
+            includeArchived: t.Optional(t.Boolean()),
+            ...paginationFields(),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id, filters, includeArchived, limit, offset } = input;
+            return call(() => clientFor(ctx).listListRecords(id, {
+                filters,
+                includeArchived,
+                limit,
+                offset,
+            }));
+        },
+    });
+}
+// ─── groups ──────────────────────────────────────────────────────
+export function registerGroupActions(rl) {
+    rl.registerAction("group.list", {
+        access: "read",
+        description: "Groups are the subjects of group visibility: { id, slug, name, description, members: [{ type: user | service, id }] }. A record with visibility.mode 'group' is readable by members of its named groups.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            return call(() => clientFor(ctx).listGroups());
+        },
+    });
+    rl.registerAction("group.create", {
+        access: "write",
+        description: "Create a group, optionally with initial members. Requires the configure scope.",
+        inputSchema: t.Object({
+            slug: t.String({
+                pattern: "^[a-z][a-z0-9_]*$",
+                maxLength: 100,
+                description: "Stable identifier, e.g. sales",
+            }),
+            name: t.String({ minLength: 1, maxLength: 200 }),
+            description: t.Optional(t.String({ minLength: 1, maxLength: 2_000 })),
+            members: t.Optional(t.Array(principalSchema)),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const body = input;
+            return call(() => idempotentClientFor(ctx).createGroup(body));
+        },
+    });
+    rl.registerAction("group.update", {
+        access: "write",
+        description: "Rename a group or change its description. Requires the configure scope. Lost races retry once.",
+        inputSchema: t.Object({
+            id: idSchema("Group ID"),
+            name: t.Optional(t.String({ minLength: 1, maxLength: 200 })),
+            description: t.Optional(t.Union([t.String({ maxLength: 2_000 }), t.Null()])),
+        }, STRICT_UPDATE_OBJECT),
+        async execute(input, ctx) {
+            const { id, ...body } = input;
+            return call(() => withConflictRetry(() => clientFor(ctx).updateGroup(id, body)));
+        },
+    });
+    rl.registerAction("group.updateMembers", {
+        access: "write",
+        description: "Add and/or remove principals (members or API keys) from a group. Membership changes take effect on the next read. Requires the configure scope.",
+        inputSchema: t.Object({
+            id: idSchema("Group ID"),
+            add: t.Optional(t.Array(principalSchema)),
+            remove: t.Optional(t.Array(principalSchema)),
+        }, STRICT_UPDATE_OBJECT),
+        async execute(input, ctx) {
+            const { id, ...body } = input;
+            return call(() => clientFor(ctx).updateGroupMembers(id, body));
+        },
+    });
+    rl.registerAction("group.delete", {
+        access: "write",
+        description: "Delete a group. Records that named only this group become unreadable to its former members. Requires the configure scope.",
+        inputSchema: t.Object({ id: idSchema("Group ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            await call(() => clientFor(ctx).deleteGroup(id));
+            return { id, deleted: true };
+        },
+    });
+}
+// ─── members ─────────────────────────────────────────────────────
+export function registerMemberActions(rl) {
+    rl.registerAction("member.list", {
+        access: "read",
+        description: "The organization's members in envelope form: { data: [{ id, fields: { $name, $email, $role } }], object: 'list', totalCount }. Use the id for $owner, $assignedTo, visibility principals ({ type: 'user', id }), and group members.",
+        inputSchema: t.Object({ ...paginationFields() }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { limit, offset } = input;
+            return call(() => clientFor(ctx).listMembers({ limit, offset }));
+        },
+    });
+}
+// ─── files ───────────────────────────────────────────────────────
+export function registerFileActions(rl) {
+    rl.registerAction("file.createUpload", {
+        access: "write",
+        description: "Start a file upload: returns the file ({ id, status: PENDING, ... }) plus a one-time grant { uploadUrl, uploadMethod, uploadHeaders, expiresAt }. PUT the bytes there yourself, then call file.complete, then attach with record.update({ relationships: { $files: { add: fileId } } }).",
+        inputSchema: t.Object({
+            filename: t.String({ minLength: 1, maxLength: 500 }),
+            mimeType: t.String({ minLength: 1, maxLength: 200 }),
+            sizeBytes: t.Integer({ minimum: 1 }),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const body = input;
+            return call(() => idempotentClientFor(ctx).createFileUpload(body));
+        },
+    });
+    rl.registerAction("file.complete", {
+        access: "write",
+        description: "Finalize an upload after the bytes were PUT to the grant URL. Returns the file with status COMPLETED.",
+        inputSchema: t.Object({ id: idSchema("File ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            return call(() => clientFor(ctx).completeFileUpload(id));
+        },
+    });
+    rl.registerAction("record.fileUrl", {
+        access: "read",
+        description: "Mint a short-lived download URL for a file attached to a record: { url, expiresAt }. Only succeeds when the caller can see the record.",
+        inputSchema: t.Object({ recordId: idSchema("Record ID"), fileId: idSchema("File ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { recordId, fileId } = input;
+            return call(() => clientFor(ctx).getRecordFileUrl(recordId, fileId));
+        },
+    });
+}

package/dist/plugins/shiftBwm/src/index.js

@@ -0,0 +1,35 @@
+import * as t from "typebox";
+import { registerFileActions, registerGroupActions, registerMemberActions, registerSavedListActions, } from "./collections.js";
+import { registerRecordActions, registerSchemaActions } from "./records.js";
+import { shiftBwmCredential } from "./shared.js";
+/**
+ * Shift Business World Model — an organization's graph of accounts,
+ * contacts, opportunities, activities, tasks, notes, and custom object
+ * types in the Shift cloud. The API key is the tenant authority; the
+ * cloud derives the organization from it (SHFT-852), so no org ID is sent.
+ *
+ * Every record is an envelope of typed `fields` and typed
+ * `relationships`; system keys are $-prefixed; definitions are published
+ * per object type and must be read before writing.
+ *
+ * Requests go through the cloud repo's own BusinessWorldModelClient,
+ * vendored under src/vendor (see the SYNCED_FROM headers there), signed
+ * through the Shift family's declared credential.
+ */
+export default function shiftBwm(rl) {
+    rl.setName("shiftBwm");
+    rl.setVersion("0.1.0");
+    rl.setCredential(shiftBwmCredential);
+    rl.setConnectionSchema(t.Object({
+        apiKey: t.String({
+            description: "Shift Labs API key. A personal token (subject: user) acts as its human and inherits that person's record visibility; an organization key (subject: service) is its own principal, named on records and added to groups like a member. Needs service:business-world-model:read for reads, :write for record writes, :configure for groups.",
+            env: "SHIFT_LABS_API_KEY",
+        }),
+    }));
+    registerSchemaActions(rl);
+    registerRecordActions(rl);
+    registerSavedListActions(rl);
+    registerGroupActions(rl);
+    registerMemberActions(rl);
+    registerFileActions(rl);
+}

package/dist/plugins/shiftBwm/src/records.js

@@ -0,0 +1,180 @@
+import * as t from "typebox";
+import { call, clientFor, ENVELOPE_DOC, fieldsWriteSchema, filtersSchema, idempotentClientFor, idSchema, objectTypeSchema, paginationFields, relationshipsCreateSchema, relationshipsUpdateSchema, STRICT_OBJECT, STRICT_UPDATE_OBJECT, visibilitySchema, withConflictRetry, } from "./shared.js";
+const READ_DEFINITIONS_FIRST = "Read definition.get for the object type before writing: it lists every field key, its valueType, and the select options. SINGLE_SELECT / MULTI_SELECT accept an option id or its label. $stage accepts a stage id, or a stage label together with a $pipeline hint. Unknown keys fail with unknown_field / unknown_relationship and the error names the offending param (fields.tier, relationships.$owner).";
+export function registerSchemaActions(rl) {
+    rl.registerAction("objectType.list", {
+        access: "read",
+        description: "List the organization's object types, built-in (account, contact, opportunity, activity, task, note) and custom. Each has slug, label, pluralLabel, system, path. Use the slug as objectType everywhere else.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            return call(() => clientFor(ctx).listObjectTypes());
+        },
+    });
+    rl.registerAction("definition.get", {
+        access: "read",
+        description: `Field and relationship definitions for one object type: everything needed to write, validate, or filter it. fieldDefinitions: { "<key>": { slug, label, valueType, system, readOnly, required, typeConfiguration: { options?: [{ id, label, parentId? }], parentFieldKey?, multipleValues?, unique? } } }. relationshipDefinitions: { "<key>": { label, cardinality: HAS_ONE | HAS_MANY, objectType, inverseKey } }. Value types: TEXT NUMBER CHECKBOX CURRENCY DATE DATETIME EMAIL TELEPHONE URL SOCIAL_HANDLE ADDRESS FULL_NAME MARKDOWN SINGLE_SELECT MULTI_SELECT JSON. Multi-value types (EMAIL, TELEPHONE, URL) take arrays.`,
+        inputSchema: t.Object({ objectType: objectTypeSchema() }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { objectType } = input;
+            return call(() => clientFor(ctx).getDefinitions(objectType));
+        },
+    });
+    rl.registerAction("pipeline.list", {
+        access: "read",
+        description: "List opportunity pipelines with their ordered stages ({ id, key, name, position, outcome: open | won | lost }). The same stages appear as $stage options in definition.get({ objectType: 'opportunity' }), each with parentId = pipeline id.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            return call(() => clientFor(ctx).listPipelines());
+        },
+    });
+}
+export function registerRecordActions(rl) {
+    rl.registerAction("record.list", {
+        access: "read",
+        description: `Query records of one object type. Returns { data: [envelopes], object: "list", totalCount }. ${ENVELOPE_DOC} Filters AND together on field or relationship keys; a hidden record is simply absent. Use this to find-or-create: filter on $email / $phone with no operator (multi-value fields reject equal), or $name with equal, then create only when totalCount is 0.`,
+        inputSchema: t.Object({
+            objectType: objectTypeSchema(),
+            filters: t.Optional(filtersSchema()),
+            includeArchived: t.Optional(t.Boolean({ description: "Also return archived records" })),
+            ...paginationFields(),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { objectType, filters, includeArchived, limit, offset } = input;
+            return call(() => clientFor(ctx).listRecords(objectType, {
+                filters,
+                includeArchived,
+                limit,
+                offset,
+            }));
+        },
+    });
+    rl.registerAction("record.get", {
+        access: "read",
+        description: `Read one record envelope by id. ${ENVELOPE_DOC} A record the caller cannot see is a 404, same as one that does not exist.`,
+        inputSchema: t.Object({ objectType: objectTypeSchema(), id: idSchema("Record ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { objectType, id } = input;
+            return call(() => clientFor(ctx).getRecord(objectType, id));
+        },
+    });
+    rl.registerAction("record.create", {
+        access: "write",
+        description: `Create a record and return its envelope. ${READ_DEFINITIONS_FIRST} Writes take bare values: fields: { "$name": "Acme", "tier": "Gold" }, relationships: { "$owner": "user_1", "$contact": ["con_1"] }. Visibility defaults to org; the actor who restricts a record is always among its readers. Every create carries an Idempotency-Key.`,
+        inputSchema: t.Object({
+            objectType: objectTypeSchema(),
+            fields: fieldsWriteSchema("Field key -> bare value. The required display key differs per type: $name on account, contact, opportunity, and custom types; $title on task and note (note body is $content, activity body is $body, both MARKDOWN); activity has no $name and requires $subject plus $type (free text, e.g. call, email, meeting). Contact identities are $email (array), $phone (array, E.164), $whatsapp (array), $linkedIn (a full https://linkedin.com/in/... URL). Required keys are marked required in definition.get."),
+            relationships: t.Optional(relationshipsCreateSchema()),
+            externalId: t.Optional(t.String({
+                minLength: 1,
+                maxLength: 500,
+                description: "Caller-owned external identifier",
+            })),
+            visibility: t.Optional(visibilitySchema()),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { objectType, ...body } = input;
+            return call(() => idempotentClientFor(ctx).createRecord(objectType, body));
+        },
+    });
+    rl.registerAction("record.update", {
+        access: "write",
+        description: `Update a record and return its envelope. Only named fields change; null clears a nullable field. Relationships take { add, remove, replace } per key, or a bare id / id array as shorthand for replace, or null to clear; HAS_ONE never holds more than one value; at most 25 link changes per request. archived: false restores an archived record. ${READ_DEFINITIONS_FIRST} Updates are compare-and-set; a lost race (409 write_conflict) is retried once automatically.`,
+        inputSchema: t.Object({
+            objectType: objectTypeSchema(),
+            id: idSchema("Record ID"),
+            fields: t.Optional(fieldsWriteSchema("Field key -> bare value")),
+            relationships: t.Optional(relationshipsUpdateSchema()),
+            externalId: t.Optional(t.Union([t.String({ maxLength: 500 }), t.Null()])),
+            visibility: t.Optional(visibilitySchema()),
+            archived: t.Optional(t.Boolean({ description: "true archives, false restores" })),
+        }, 
+        // objectType and id both route the request, so a change is a third key.
+        { ...STRICT_UPDATE_OBJECT, minProperties: 3 }),
+        async execute(input, ctx) {
+            const { objectType, id, ...body } = input;
+            return call(() => withConflictRetry(() => clientFor(ctx).updateRecord(objectType, id, body)));
+        },
+    });
+    rl.registerAction("record.archive", {
+        access: "write",
+        description: "Archive a record (soft delete). It leaves default listings, stays readable with includeArchived, and record.update({ archived: false }) restores it. Nothing is destroyed. Returns the archived envelope.",
+        inputSchema: t.Object({ objectType: objectTypeSchema(), id: idSchema("Record ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { objectType, id } = input;
+            return call(() => clientFor(ctx).archiveRecord(objectType, id));
+        },
+    });
+    rl.registerAction("record.history", {
+        access: "read",
+        description: 'Values of one field over time, newest first, consecutive duplicates collapsed: { data: [{ value, valueType, displayValue, recordedAt, isCreate }], hasMore, nextCursor }. Every field has history, system and custom alike. Use it for "what changed on X and when".',
+        inputSchema: t.Object({
+            objectType: objectTypeSchema(),
+            id: idSchema("Record ID"),
+            field: t.String({
+                minLength: 1,
+                description: "Field key, e.g. $name, $stage, tier",
+            }),
+            limit: t.Optional(t.Integer({ minimum: 1, maximum: 100, description: "Default 20" })),
+            after: t.Optional(t.String({
+                minLength: 1,
+                description: "nextCursor from a prior page",
+            })),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { objectType, id, field, limit, after } = input;
+            return call(() => clientFor(ctx).getFieldHistory(objectType, id, field, { limit, after }));
+        },
+    });
+    rl.registerAction("record.links", {
+        access: "read",
+        description: "Raw edges touching a record: { outbound: [link], inbound: [link] } where link = { id, fromRecordId, toRecordId, fromObjectType, toObjectType, key, role, attributes, declared, createdAt }. declared is false for an edge no definition covers. Edges whose far end the caller cannot see are hidden.",
+        inputSchema: t.Object({
+            id: idSchema("Record ID"),
+            direction: t.Optional(t.Union([t.Literal("in"), t.Literal("out"), t.Literal("both")], {
+                description: "Default both",
+            })),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id, direction } = input;
+            return call(() => clientFor(ctx).listLinks(id, direction));
+        },
+    });
+    rl.registerAction("record.changeEvents", {
+        access: "read",
+        description: "Immutable change events for a record: [{ id, recordId, actor: { type, id }, action: created | updated, before, after, importRunId, createdAt }]. before/after are whole-record snapshots. Prefer record.history when only one field matters.",
+        inputSchema: t.Object({ id: idSchema("Record ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            return call(() => clientFor(ctx).listChangeEvents(id));
+        },
+    });
+    rl.registerAction("record.merge", {
+        access: "write",
+        description: "Fold a duplicate record into a primary of the same object type in one transaction. Fields keep the primary's value unless it is empty or fieldResolutions names 'duplicate' or a literal { value }; multi-value fields union; every edge, identity, list membership, file, and reader moves to the primary; the duplicate archives with mergedIntoId. Returns { merge: { id, status, summary }, primary, summary }.",
+        inputSchema: t.Object({
+            objectType: objectTypeSchema(),
+            primaryId: idSchema("Record that survives"),
+            duplicateId: idSchema("Record folded into the primary"),
+            fieldResolutions: t.Optional(t.Record(t.String(), t.Union([
+                t.Literal("primary"),
+                t.Literal("duplicate"),
+                t.Object({ value: t.Unknown() }, STRICT_OBJECT),
+            ]), {
+                description: "Per field key: keep primary, take duplicate, or set a literal value",
+            })),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { objectType, ...body } = input;
+            return call(() => idempotentClientFor(ctx).mergeRecords(objectType, body));
+        },
+    });
+    rl.registerAction("merge.get", {
+        access: "read",
+        description: "Read a past merge by id: { id, objectType, primaryId, duplicateId, status: done | failed, summary: { fieldWriteCount, repointedCount, warnings }, createdAt }.",
+        inputSchema: t.Object({ id: idSchema("Merge ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            return call(() => clientFor(ctx).getMerge(id));
+        },
+    });
+}

package/dist/plugins/shiftBwm/src/shared.js

@@ -0,0 +1,168 @@
+import { AuthError } from "runline";
+import * as t from "typebox";
+import { credentialBroker } from "../../_shared/credentialAdapter.js";
+import { errorIdentifier, failureMessage } from "../../_shared/credentials.js";
+import { SHIFT_API_URL, STRICT_OBJECT } from "../../_shared/shiftCloud.js";
+import { shiftCredential, shiftPath } from "../../_shared/shiftCredentials.js";
+import { BusinessWorldModelClient, BwmClientError, } from "./vendor/client.js";
+import { BWM_BUILT_IN_OBJECT_TYPES, BWM_LIST_MAX_LIMIT, } from "./vendor/contracts.js";
+import { BwmFilterOperator } from "./vendor/models.js";
+export { idSchema, STRICT_OBJECT, STRICT_UPDATE_OBJECT, } from "../../_shared/shiftCloud.js";
+export const shiftBwmCredential = shiftCredential();
+// ─── client ──────────────────────────────────────────────────────
+/**
+ * The vendored client's fetch, sent through the declared credential: the
+ * client names Shift API URLs, and each becomes a path beneath the Shift
+ * target. The client never holds the key.
+ */
+function brokeredFetch(ctx) {
+    return (input, init) => {
+        const url = new URL(input);
+        if (url.origin !== SHIFT_API_URL)
+            throw new AuthError("request_not_allowed");
+        return credentialBroker(ctx, shiftBwmCredential).request({
+            target: "api",
+            path: `${shiftPath(url.pathname)}${url.search}`,
+            method: (init?.method ?? "GET"),
+            headers: {
+                Accept: "application/json",
+                ...Object.fromEntries(init?.headers ?? []),
+            },
+            ...(init?.body !== undefined ? { body: init.body } : {}),
+        });
+    };
+}
+/**
+ * One client per call. Cheap (prefix + fetch closure), and it lets a
+ * create attach its own `Idempotency-Key` without leaking it into the
+ * next request.
+ */
+export function clientFor(ctx, extraHeaders = {}) {
+    return new BusinessWorldModelClient({
+        baseUrl: SHIFT_API_URL,
+        fetch: brokeredFetch(ctx),
+        headers: extraHeaders,
+    });
+}
+/** Client whose every mutation carries a fresh `Idempotency-Key`. */
+export function idempotentClientFor(ctx) {
+    return clientFor(ctx, { "idempotency-key": crypto.randomUUID() });
+}
+// ─── errors ──────────────────────────────────────────────────────
+/**
+ * Only `message` survives the trip back to the agent's code, so the
+ * fields the model needs to self-correct — `code` and `param` — are
+ * folded into it, as for every Shift plugin. `param` names the offending
+ * request location (`fields.tier`, `relationships.$owner`). The service's
+ * free-text message can echo request data and is not returned.
+ */
+export function describeError(err) {
+    if (err instanceof BwmClientError) {
+        const code = errorIdentifier(err.code);
+        const param = errorIdentifier(err.param);
+        const error = new Error(failureMessage("shiftBwm", err.status, { code, param }));
+        error.status = err.status;
+        error.type = errorIdentifier(err.type);
+        error.code = code;
+        error.param = param;
+        return error;
+    }
+    return err instanceof Error ? err : new Error(String(err));
+}
+export async function call(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        throw describeError(err);
+    }
+}
+/**
+ * Every update is compare-and-set on `updatedAt`; a lost race is
+ * `409 write_conflict`. The API asks the loser to re-read and retry,
+ * so an update runs once more after a conflict before it fails.
+ */
+export async function withConflictRetry(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof BwmClientError && err.code === "write_conflict") {
+            return await fn();
+        }
+        throw err;
+    }
+}
+// ─── schema helpers ──────────────────────────────────────────────
+export function objectTypeSchema(description = `Object type: ${BWM_BUILT_IN_OBJECT_TYPES.join(" | ")} or a custom type's slug (see objectType.list).`) {
+    return t.String({ minLength: 1, pattern: "^[a-z][a-z0-9_]*$", description });
+}
+export const idOrIds = t.Union([
+    t.String({ minLength: 1 }),
+    t.Array(t.String({ minLength: 1 })),
+]);
+/** Link changes on one relationship key, as records and lists both take them. */
+export const relationshipChangeSchema = t.Union([
+    idOrIds,
+    t.Object({
+        add: t.Optional(idOrIds),
+        remove: t.Optional(idOrIds),
+        replace: t.Optional(t.Union([idOrIds, t.Null()])),
+    }, STRICT_OBJECT),
+]);
+export const principalSchema = t.Object({
+    type: t.Union([t.Literal("user"), t.Literal("service")], {
+        description: "user: a member (see member.list). service: an API key.",
+    }),
+    id: t.String({ minLength: 1 }),
+}, STRICT_OBJECT);
+export function fieldsWriteSchema(description) {
+    return t.Record(t.String(), t.Unknown(), { description });
+}
+export function relationshipsCreateSchema() {
+    return t.Record(t.String(), idOrIds, {
+        description: "Relationship key -> record id (HAS_ONE) or array of ids (HAS_MANY). System keys are $-prefixed ($owner, $account, $contact, $attendee, $assignedTo, $files); custom keys are bare slugs.",
+    });
+}
+export function relationshipsUpdateSchema() {
+    return t.Record(t.String(), t.Union([relationshipChangeSchema, t.Null()]), {
+        description: "Relationship key -> { add, remove, replace } ops, or a bare id / id array as shorthand for replace, or null to clear. At most 25 link changes per request.",
+    });
+}
+export function visibilitySchema() {
+    return t.Object({
+        mode: t.Union([t.Literal("org"), t.Literal("group"), t.Literal("private")], {
+            description: "org: every member. group: members of the named groups. private: only the named principals. The actor who restricts a record is always a reader.",
+        }),
+        groups: t.Optional(t.Array(t.String({ minLength: 1 }))),
+        principals: t.Optional(t.Array(principalSchema)),
+    }, STRICT_OBJECT);
+}
+export function paginationFields() {
+    return {
+        limit: t.Optional(t.Integer({
+            minimum: 1,
+            maximum: BWM_LIST_MAX_LIMIT,
+            description: `Page size, default 25, max ${BWM_LIST_MAX_LIMIT}`,
+        })),
+        offset: t.Optional(t.Integer({ minimum: 0, description: "Default 0" })),
+    };
+}
+export function filtersSchema() {
+    const operators = BwmFilterOperator.options;
+    return t.Array(t.Object({
+        key: t.String({
+            minLength: 1,
+            description: "Field or relationship key, e.g. $name, $email, tier, $account",
+        }),
+        operator: t.Optional(t.Union(operators.map((op) => t.Literal(op)), {
+            description: `${operators.join(" | ")}. Omit it and the API picks equal where valid, contains otherwise. Multi-value fields (EMAIL, TELEPHONE, URL) reject equal (unsupported_filter_operator): omit the operator or use contains.`,
+        })),
+        negate: t.Optional(t.Boolean({ description: "Negate the operator" })),
+        value: t.String({
+            description: "Comparison value. For relationship keys, a related record id.",
+        }),
+    }, STRICT_OBJECT), { description: "AND-ed filters" });
+}
+/** The record envelope, as every read returns it and as descriptions cite it. */
+export const ENVELOPE_DOC = `Record envelope: { id, objectType, createdAt, updatedAt, archivedAt, mergedIntoId, externalId, visibility: { mode, groups, principals }, fields: { "<key>": { value, valueType } }, relationships: { "<key>": { cardinality, objectType, values: [ids] } } }. System keys are $-prefixed ($name, $email, $owner, $account, $stage, ...); custom keys are bare slugs. Writes take bare values: fields: { "$name": "Acme" }, relationships: { "$owner": "user_1", "$contact": ["con_1"] }.`;