@catalyst-cloud/sdk 0.8.49 → 0.9.0

package/dist/tenant-contract.d.ts

@@ -0,0 +1,237 @@
+/** The eleven stage slots `teams[].stages` is keyed by. Served as `slots` on the wire, in this order. */
+export type WorkflowSlot = "dispatch" | "intake" | "research" | "plan" | "implement" | "remediate" | "verify" | "review" | "pr" | "done" | "canceled";
+/** ⛔ `unscoped`, NOT `workspace` — the mirror's `labels.team_id` is advisory (NULL means either
+ *  "genuinely workspace-scoped" or "not re-stamped yet"), so the document reports what was read. */
+export type LabelScopeKind = "unscoped" | "team" | "absent";
+export interface ContractLabel {
+    name: string;
+    unscopedId: string | null;
+    teamScopedId: string | null;
+    scope: LabelScopeKind;
+    /** The id `scope` resolves to (the unscoped copy wins); `null` when `scope` is `absent`. */
+    preferredId: string | null;
+}
+export interface ContractStage {
+    /** Linear's state id — THE join key. Address stages by slot, and states by this. */
+    stateId: string;
+    /** The state's CURRENT name, read live — never the mapping's write-time snapshot. */
+    name: string | null;
+    type: string | null;
+    /** False when the mapped id is not in the team's live stage set (archived, or re-minted). */
+    stateStillExists: boolean;
+    /** How the mapping was made: created | matched | chosen. */
+    source: string;
+}
+export interface ContractReadinessCheck {
+    id: string;
+    state: "pass" | "fail" | "unknown";
+    reason?: string;
+    count?: number;
+}
+export interface ContractTeam {
+    id: string;
+    key: string | null;
+    name: string | null;
+    workflowMode: string;
+    gitAutomation: string;
+    /** Keyed by slot. An UNMAPPED slot is ABSENT — never a placeholder. */
+    stages: Partial<Record<WorkflowSlot, ContractStage>>;
+    labels: {
+        ask: ContractLabel[];
+        hold: ContractLabel[];
+        release: ContractLabel[];
+    };
+    readiness: {
+        /** `unchecked` means no verdict has ever been computed — a real answer, not `blocked`. */
+        status: "ready" | "degraded" | "blocked" | "unchecked";
+        checks: ContractReadinessCheck[];
+        checkedAt: number | null;
+        expiresAt: number | null;
+        workflowRev: number | null;
+    };
+}
+export interface ContractRoute {
+    method: "GET" | "POST";
+    path: string;
+    /** Whether a call spends a unit of the per-host daily write budget. */
+    takesWriteBudgetUnit: boolean;
+    /** The contract version this route first appeared in. */
+    since: string;
+}
+export interface ContractMergeRepository {
+    repoId: string;
+    owner: string;
+    name: string;
+    /** The EFFECTIVE policy after repo-wins-over-tenant precedence. */
+    policy: string;
+    policySource: "repo" | "tenant" | "default";
+}
+export interface ContractMergeCleanPassShape {
+    kind: string;
+    description: string;
+    /** FALSE means the cloud does NOT accept this shape today. */
+    honoured: boolean;
+    ticket: string | null;
+}
+export interface ContractAdvanceRule {
+    phase: string;
+    result: "ok" | "failed";
+    fromSlots: readonly WorkflowSlot[] | null;
+    toSlot: WorkflowSlot | null;
+    because: string;
+}
+export interface TenantContract {
+    /** Semver over the DOCUMENT'S SHAPE (MAJOR: meaning changed/removed; MINOR: additive). */
+    contractVersion: string;
+    protocolVersion: number;
+    /** The cloud states the freshness bounds; the CLIENT measures its own age against them. */
+    cache: {
+        maxAgeSeconds: number;
+        staleRefusalSeconds: number;
+    };
+    account: {
+        id: string;
+        slug: string;
+        name: string;
+        linearWorkspaceId: string | null;
+        linearWorkspaceSlug: string | null;
+    };
+    apiPrefix: string;
+    slots: readonly WorkflowSlot[];
+    routes: readonly ContractRoute[];
+    teams: ContractTeam[];
+    vocabulary: {
+        askLabelPrefix: string;
+        askPhaseLabelPrefix: string;
+        askMarkerLabel: string;
+        releaseLabel: string;
+        bookkeeping: {
+            marker: string;
+            prefixOnly: boolean;
+            asciiCaseInsensitive: boolean;
+            leadingWhitespaceTrimmed: boolean;
+        };
+    };
+    askTemplate: {
+        headings: {
+            ask: string;
+            options: string;
+            defaultIfSilent: string;
+            howToAnswer: string;
+        };
+        howToAnswer: {
+            withOptions: string;
+            withoutOptions: string;
+        };
+        optionBulletFormat: string;
+        maxLetteredOptions: number;
+        maxAskGenerations: number;
+        example: string;
+    };
+    ladder: {
+        phases: readonly string[];
+        keying: string;
+        keyingScope: string;
+        /** `phases` is the full vocabulary; this says whether `intake` actually runs. */
+        intakeEnabled: boolean;
+        advance: readonly ContractAdvanceRule[];
+    };
+    thresholds: {
+        scope: string;
+        parkAfterConsecutiveFailures: number;
+        remediateRoundCap: number;
+        remediateEscalatedRoundBudget: number;
+        remediateRewindBudget: number;
+        retryBackoffMs: readonly number[];
+        hostDailyWriteBudget: number;
+    };
+    merge: {
+        policies: readonly string[];
+        defaultPolicy: string;
+        repositories: readonly ContractMergeRepository[];
+        reviewerLogin: string;
+        cleanPassShapes: readonly ContractMergeCleanPassShape[];
+        cloudRemediateRequiredChecks: readonly string[];
+        prLabels: {
+            queueReady: string;
+            handStepsHold: string;
+            hold: string;
+            preview: string;
+        };
+    };
+    readinessChecks: readonly {
+        id: string;
+        severity: string;
+        needsAnswer: boolean;
+    }[];
+    humans: readonly {
+        linearUserId: string;
+        role: "owner" | "admin";
+    }[];
+    asks: {
+        /** `null` means NOT CONFIGURED, and a consumer must refuse rather than guess. */
+        approvalsTeamId: string | null;
+    };
+}
+/** The one path a consumer knows a priori — the address the document itself is served from. */
+export declare const CONTRACT_ROUTE = "/api/v1/agent/contract";
+/**
+ * The document's top-level keys, as a runtime list, in lockstep with {@link TenantContract} — the
+ * drift test asserts the two agree at compile time, and {@link readTenantContract} requires every
+ * one of them on the wire. Kept alphabetical so the fixture comparison is order-independent.
+ */
+export declare const TENANT_CONTRACT_KEYS: readonly ["account", "apiPrefix", "askTemplate", "asks", "cache", "contractVersion", "humans", "ladder", "merge", "protocolVersion", "readinessChecks", "routes", "slots", "teams", "thresholds", "vocabulary"];
+/**
+ * The shape guard the client applies to every 200 from the contract route. Structural, not
+ * exhaustive: it requires every top-level key, and checks the load-bearing legs a consumer will
+ * immediately index into (`cache`'s two bounds, `routes[]`'s method/path, `teams[]`'s id/stages/
+ * labels/readiness, `slots[]`). A type predicate, so the narrowing is the compiler's — no cast.
+ */
+export declare function isTenantContract(value: unknown): value is TenantContract;
+/** {@link isTenantContract} as a read: the typed document, or `null` — never a throw, because the
+ *  caller's answer to a malformed document is a typed `shape` outcome, not an exception. */
+export declare function readTenantContract(value: unknown): TenantContract | null;
+/** The route whose LAST path segment is `name` (`issue-comment`); the path itself is never assumed. */
+export declare function routeByName(doc: TenantContract, name: string): ContractRoute | null;
+export type TeamLookup = {
+    outcome: "ok";
+    team: ContractTeam;
+} | {
+    outcome: "team-unknown";
+    key: string;
+    known: string[];
+} | {
+    outcome: "ticket-shape";
+    ticket: string;
+};
+export declare function teamByKey(doc: TenantContract, key: string): TeamLookup;
+/** The team a ticket identifier belongs to, by its `KEY-` prefix. */
+export declare function teamForTicket(doc: TenantContract, ticket: string): TeamLookup;
+export type StageLookup = {
+    outcome: "ok";
+    stateId: string;
+} | {
+    outcome: "slot-unmapped";
+    slot: string;
+    mapped: string[];
+} | {
+    outcome: "slot-stale";
+    slot: string;
+    stateId: string;
+};
+/** The Linear state id a slot maps to on this team. An unmapped slot and a stale mapping are two
+ *  DIFFERENT answers (docs/agent-contract.md rule 1) and are reported by name. */
+export declare function stageIdForSlot(team: ContractTeam, slot: string): StageLookup;
+export type LabelLookup = {
+    outcome: "ok";
+    labelId: string;
+} | {
+    outcome: "label-absent";
+    name: string;
+    scope: LabelScopeKind;
+};
+/** Resolve a label by NAME through the contract's ask/hold/release lists to its `preferredId`. A name
+ *  the contract does not list is passed through as an id the caller already holds (the contract
+ *  only lists Catalyst's own labels); `scope: "absent"` is a real, reported answer, never an id. */
+export declare function labelIdFor(team: ContractTeam, nameOrId: string): LabelLookup;
+//# sourceMappingURL=tenant-contract.d.ts.map

package/dist/tenant-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-contract.d.ts","sourceRoot":"","sources":["../src/tenant-contract.ts"],"names":[],"mappings":"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"}

package/dist/tenant-contract.js

@@ -0,0 +1,183 @@
+// tenant-contract.ts — CTC-2004. The SHAPE of GET /api/v1/agent/contract as this SDK reads it, plus
+// the pure accessors a consumer needs over it.
+//
+// ⛔ SELF-CONTAINED ON PURPOSE. The cloud declares this document in `@catalyst-cloud/types`
+// (packages/types/src/tenant-contract.ts), a PRIVATE workspace package this SDK cannot import — the
+// same constraint `src/types.ts` states for the change-feed contract. So this module is the SDK's own
+// copy, structurally the cloud's, and test/tenant-contract.test.ts pins it against the fixture the
+// cloud commits (packages/types/fixtures/tenant-contract.fixture.json — built by the real
+// `buildTenantContract`, regenerated by `bun run contract:fixture`) so a cloud-side shape change
+// reddens here as a fixture diff rather than surfacing as a silent wrong answer in a customer's skill.
+//
+// ⛔ NO FIELD BELOW CARRIES A DEFAULT. Every value is filled from the wire; a tenant fact the contract
+// does not serve is reported as a typed miss (`slot-unmapped`, `label-absent`, `route-unknown`), never
+// guessed. That is the whole point of the document (docs/agent-contract.md): a consumer that falls
+// back to a remembered literal has reintroduced the defect the contract exists to retire.
+//
+// This module is free of any runtime-specific import — pure type declarations + plain functions — so
+// it imports cleanly into a browser bundle or a node/bun app alike.
+/** The one path a consumer knows a priori — the address the document itself is served from. */
+export const CONTRACT_ROUTE = "/api/v1/agent/contract";
+/**
+ * The document's top-level keys, as a runtime list, in lockstep with {@link TenantContract} — the
+ * drift test asserts the two agree at compile time, and {@link readTenantContract} requires every
+ * one of them on the wire. Kept alphabetical so the fixture comparison is order-independent.
+ */
+export const TENANT_CONTRACT_KEYS = [
+    "account",
+    "apiPrefix",
+    "askTemplate",
+    "asks",
+    "cache",
+    "contractVersion",
+    "humans",
+    "ladder",
+    "merge",
+    "protocolVersion",
+    "readinessChecks",
+    "routes",
+    "slots",
+    "teams",
+    "thresholds",
+    "vocabulary",
+];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * The shape guard the client applies to every 200 from the contract route. Structural, not
+ * exhaustive: it requires every top-level key, and checks the load-bearing legs a consumer will
+ * immediately index into (`cache`'s two bounds, `routes[]`'s method/path, `teams[]`'s id/stages/
+ * labels/readiness, `slots[]`). A type predicate, so the narrowing is the compiler's — no cast.
+ */
+export function isTenantContract(value) {
+    if (!isRecord(value))
+        return false;
+    for (const key of TENANT_CONTRACT_KEYS)
+        if (!(key in value))
+            return false;
+    if (typeof value["contractVersion"] !== "string")
+        return false;
+    if (typeof value["protocolVersion"] !== "number")
+        return false;
+    const cache = value["cache"];
+    if (!isRecord(cache) ||
+        typeof cache["maxAgeSeconds"] !== "number" ||
+        typeof cache["staleRefusalSeconds"] !== "number") {
+        return false;
+    }
+    const account = value["account"];
+    if (!isRecord(account) || typeof account["id"] !== "string" || typeof account["slug"] !== "string") {
+        return false;
+    }
+    const routes = value["routes"];
+    if (!Array.isArray(routes) ||
+        !routes.every((r) => isRecord(r) &&
+            (r["method"] === "GET" || r["method"] === "POST") &&
+            typeof r["path"] === "string" &&
+            typeof r["takesWriteBudgetUnit"] === "boolean" &&
+            typeof r["since"] === "string")) {
+        return false;
+    }
+    const slots = value["slots"];
+    if (!Array.isArray(slots) || !slots.every((s) => typeof s === "string"))
+        return false;
+    const teams = value["teams"];
+    if (!Array.isArray(teams) || !teams.every(isContractTeam))
+        return false;
+    const vocabulary = value["vocabulary"];
+    if (!isRecord(vocabulary) ||
+        !isRecord(vocabulary["bookkeeping"]) ||
+        typeof vocabulary["bookkeeping"]["marker"] !== "string") {
+        return false;
+    }
+    return isRecord(value["thresholds"]) && isRecord(value["merge"]) && isRecord(value["ladder"]);
+}
+function isNullableString(value) {
+    return value === null || typeof value === "string";
+}
+function isContractLabel(value) {
+    return (isRecord(value) &&
+        typeof value["name"] === "string" &&
+        isNullableString(value["preferredId"]) &&
+        (value["scope"] === "unscoped" || value["scope"] === "team" || value["scope"] === "absent"));
+}
+function isContractStage(value) {
+    return (isRecord(value) &&
+        typeof value["stateId"] === "string" &&
+        typeof value["stateStillExists"] === "boolean");
+}
+/**
+ * ⛔ THE NESTED LEGS ARE CHECKED, NOT JUST THEIR PRESENCE (Codex #65 r1, P2). The typed accessors
+ * spread `team.labels.ask` and upper-case `team.key`; a document that passed the guard with
+ * `labels: {}` or `key: 5` would reach them as `ok` and throw there, one call later, instead of
+ * answering `shape` at the one place that read the wire.
+ */
+function isContractTeam(value) {
+    if (!isRecord(value) || typeof value["id"] !== "string" || !isNullableString(value["key"])) {
+        return false;
+    }
+    const stages = value["stages"];
+    if (!isRecord(stages) || !Object.values(stages).every(isContractStage))
+        return false;
+    const labels = value["labels"];
+    if (!isRecord(labels) ||
+        !["ask", "hold", "release"].every((k) => {
+            const list = labels[k];
+            return Array.isArray(list) && list.every(isContractLabel);
+        })) {
+        return false;
+    }
+    const readiness = value["readiness"];
+    return (isRecord(readiness) &&
+        typeof readiness["status"] === "string" &&
+        Array.isArray(readiness["checks"]));
+}
+/** {@link isTenantContract} as a read: the typed document, or `null` — never a throw, because the
+ *  caller's answer to a malformed document is a typed `shape` outcome, not an exception. */
+export function readTenantContract(value) {
+    return isTenantContract(value) ? value : null;
+}
+// ── Pure accessors — the bundle's contract.ts helpers, returning results instead of throwing ──────
+/** The route whose LAST path segment is `name` (`issue-comment`); the path itself is never assumed. */
+export function routeByName(doc, name) {
+    return doc.routes.find((r) => r.path.split("/").filter(Boolean).at(-1) === name) ?? null;
+}
+export function teamByKey(doc, key) {
+    const wanted = key.toUpperCase();
+    const team = doc.teams.find((t) => (t.key ?? "").toUpperCase() === wanted);
+    if (team === undefined) {
+        return { outcome: "team-unknown", key: wanted, known: doc.teams.map((t) => t.key ?? t.id) };
+    }
+    return { outcome: "ok", team };
+}
+/** The team a ticket identifier belongs to, by its `KEY-` prefix. */
+export function teamForTicket(doc, ticket) {
+    const dash = ticket.indexOf("-");
+    if (dash <= 0)
+        return { outcome: "ticket-shape", ticket };
+    return teamByKey(doc, ticket.slice(0, dash));
+}
+/** The Linear state id a slot maps to on this team. An unmapped slot and a stale mapping are two
+ *  DIFFERENT answers (docs/agent-contract.md rule 1) and are reported by name. */
+export function stageIdForSlot(team, slot) {
+    const stage = team.stages[slot];
+    if (stage === undefined)
+        return { outcome: "slot-unmapped", slot, mapped: Object.keys(team.stages) };
+    if (!stage.stateStillExists)
+        return { outcome: "slot-stale", slot, stateId: stage.stateId };
+    return { outcome: "ok", stateId: stage.stateId };
+}
+/** Resolve a label by NAME through the contract's ask/hold/release lists to its `preferredId`. A name
+ *  the contract does not list is passed through as an id the caller already holds (the contract
+ *  only lists Catalyst's own labels); `scope: "absent"` is a real, reported answer, never an id. */
+export function labelIdFor(team, nameOrId) {
+    const all = [...team.labels.ask, ...team.labels.hold, ...team.labels.release];
+    const hit = all.find((l) => l.name === nameOrId);
+    if (hit === undefined)
+        return { outcome: "ok", labelId: nameOrId };
+    if (hit.preferredId === null)
+        return { outcome: "label-absent", name: hit.name, scope: hit.scope };
+    return { outcome: "ok", labelId: hit.preferredId };
+}
+//# sourceMappingURL=tenant-contract.js.map

package/dist/tenant-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-contract.js","sourceRoot":"","sources":["../src/tenant-contract.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/sdk",
-  "version": "0.8.49",
+  "version": "0.9.0",
   "description": "Keep a live local copy of your Linear and GitHub project data — pushed in real time, without polling rate limits or webhook tunnels.",
   "license": "MIT",
   "author": "Coalesce Labs",
@@ -79,8 +79,8 @@
   },
   "dependencies": {
     "@catalyst-cloud/read-model": "^0.1.0",
-    "@catalyst-cloud/replicate": "0.1.46",
-    "@catalyst-cloud/schema": "0.1.52"
+    "@catalyst-cloud/replicate": "0.1.47",
+    "@catalyst-cloud/schema": "0.1.53"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.3.0 <2",