@cat-factory/contracts 0.274.0 → 0.276.0

package/dist/public-board.d.ts

@@ -0,0 +1,276 @@
+import * as v from 'valibot';
+/**
+ * The repository a new service frame is backed by.
+ *
+ * `repoId` is the provider's own id for the repo, as `GET /api/v1/repos` serves it: the neutral
+ * name for what the internal projection calls `githubId`. It is deliberately not an `owner/name`
+ * pair: a repo can be renamed or transferred without changing its id, and a caller that held a name
+ * would silently create a service against a different repository after such a move.
+ */
+export declare const publicServiceRepoSchema: v.ObjectSchema<{
+    /** The repo's provider id, from `GET /api/v1/repos`. */
+    readonly repoId: v.NumberSchema<undefined>;
+    /**
+     * For a MONOREPO, the subdirectory (relative to the repo root) this service lives in, e.g.
+     * `packages/api`. Required when the repo is a monorepo and refused for a whole-repo service,
+     * because it is what scopes each agent's working directory: a monorepo backs one service per
+     * subdirectory, and two services claiming the same one would fight over the same subtree.
+     */
+    readonly directory: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 400, undefined>]>, undefined>;
+    /**
+     * Whether the repository hosts SEVERAL services. Sent with the create rather than as a separate
+     * up-front write; when supplied it is persisted on the repo, so the flag a later create reads is
+     * the one this call set. Omitted ⇒ whatever the repo already says.
+     */
+    readonly monorepo: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicServiceRepo = v.InferOutput<typeof publicServiceRepoSchema>;
+/**
+ * Create a board service (a service frame), optionally backed by a repository.
+ *
+ * Without `repo` the frame is a structural placeholder: it can hold tasks, and a run started on one
+ * of them is REFUSED, because execution resolves a task's repository by walking up to the enclosing
+ * service frame and there is nothing there. That is a legitimate intermediate state (a caller
+ * mapping out a board before its repositories exist) and it is why the field is optional rather
+ * than why it should usually be omitted.
+ *
+ * There is deliberately no `position`: see the note at the top of this file.
+ */
+export declare const createPublicServiceSchema: v.ObjectSchema<{
+    /**
+     * The service's name. Optional, because a repo-backed service is named after the repository (or,
+     * for a monorepo service, after its subdirectory) exactly as the app's import does, and a caller
+     * that has no better name should get that one rather than being made to invent it.
+     */
+    readonly title: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
+    /** What the service is, for the agents that read it as context. Defaults to a generated line. */
+    readonly description: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+    /**
+     * The service's architectural role. Omitted ⇒ `service`.
+     *
+     * Narrower than the board's own block types on purpose: this is the set a REPOSITORY can back,
+     * which is the only kind of frame this endpoint creates. A `database` or `queue` frame documents
+     * infrastructure for the agents to read and runs nothing, so nothing here would create one.
+     */
+    readonly type: v.OptionalSchema<v.PicklistSchema<["service", "frontend", "library", "document"], undefined>, undefined>;
+    /** The repository backing the service. Omitted ⇒ an unlinked frame (see above). */
+    readonly repo: v.OptionalSchema<v.ObjectSchema<{
+        /** The repo's provider id, from `GET /api/v1/repos`. */
+        readonly repoId: v.NumberSchema<undefined>;
+        /**
+         * For a MONOREPO, the subdirectory (relative to the repo root) this service lives in, e.g.
+         * `packages/api`. Required when the repo is a monorepo and refused for a whole-repo service,
+         * because it is what scopes each agent's working directory: a monorepo backs one service per
+         * subdirectory, and two services claiming the same one would fight over the same subtree.
+         */
+        readonly directory: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 400, undefined>]>, undefined>;
+        /**
+         * Whether the repository hosts SEVERAL services. Sent with the create rather than as a separate
+         * up-front write; when supplied it is persisted on the repo, so the flag a later create reads is
+         * the one this call set. Omitted ⇒ whatever the repo already says.
+         */
+        readonly monorepo: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type CreatePublicServiceInput = v.InferOutput<typeof createPublicServiceSchema>;
+/**
+ * A repository this workspace can back a service with, as `GET /api/v1/repos` lists it.
+ *
+ * The discovery half of {@link publicServiceRepoSchema}, and it is why service creation is usable
+ * headlessly at all: the create takes a `repoId`, and until this existed the only way to learn one
+ * was to open the app. Deliberately a small projection (enough to recognise a repository and pass
+ * it back), not a mirror of the internal projection row, which carries installation ids and
+ * sync bookkeeping that are this platform's business rather than a caller's.
+ */
+export declare const publicRepoSchema: v.ObjectSchema<{
+    /** The provider's id for the repo: the value to pass as `repo.repoId`. */
+    readonly repoId: v.NumberSchema<undefined>;
+    /** Which provider it lives on (`github` / `gitlab`). */
+    readonly provider: v.StringSchema<undefined>;
+    readonly owner: v.StringSchema<undefined>;
+    readonly name: v.StringSchema<undefined>;
+    /**
+     * The branch a run's work is based on and merged into, or EMPTY when the projection has not
+     * recorded one yet (a repository connected moments ago, before its first sync). Empty rather
+     * than null because there is nothing here that could invent a default, and a caller reading it
+     * to name a base needs to see that it has to ask the provider rather than assume `main`.
+     */
+    readonly defaultBranch: v.StringSchema<undefined>;
+    /** Whether the repository is private on its provider. */
+    readonly private: v.BooleanSchema<undefined>;
+    /** Whether the repo is flagged as hosting several services (see `repo.monorepo`). */
+    readonly monorepo: v.BooleanSchema<undefined>;
+    /**
+     * The service this repository already backs ON THIS BOARD, or null.
+     *
+     * Present because a whole-repo repository backs at most ONE service, so a caller choosing one to
+     * create against needs to know which choices are already spent, and, more usefully, because a
+     * caller re-running its provisioning finds the service it created last time here rather than
+     * discovering it through a `409`. A monorepo answers null even when its subdirectories back
+     * services, since it can back more.
+     *
+     * Null and {@link linkedElsewhere} together are the honest answer when the service is homed on
+     * another board of the account: read the flag before treating null as "available".
+     */
+    readonly serviceId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * True when this repository already backs a whole-repo service homed on ANOTHER board of the
+     * account, so `POST /api/v1/services` will refuse it (`reason: repo_service_homed_elsewhere`).
+     *
+     * A service is account-owned and a board can MOUNT one homed elsewhere, but every read on this
+     * API is scoped to the calling key's own workspace, so a frame homed on another board has no id
+     * this surface could hand back: it would not appear in `GET /api/v1/services` and
+     * `POST /api/v1/services/{serviceId}/tasks` would 404 on it. Hence a flag rather than a second
+     * id field — this states that the choice is spent without naming an address that does not work
+     * here. Use the board that homes the service, or a key scoped to it.
+     */
+    readonly linkedElsewhere: v.BooleanSchema<undefined>;
+}, undefined>;
+export type PublicRepo = v.InferOutput<typeof publicRepoSchema>;
+export declare const publicRepoListSchema: v.ObjectSchema<{
+    readonly repos: v.ArraySchema<v.ObjectSchema<{
+        /** The provider's id for the repo: the value to pass as `repo.repoId`. */
+        readonly repoId: v.NumberSchema<undefined>;
+        /** Which provider it lives on (`github` / `gitlab`). */
+        readonly provider: v.StringSchema<undefined>;
+        readonly owner: v.StringSchema<undefined>;
+        readonly name: v.StringSchema<undefined>;
+        /**
+         * The branch a run's work is based on and merged into, or EMPTY when the projection has not
+         * recorded one yet (a repository connected moments ago, before its first sync). Empty rather
+         * than null because there is nothing here that could invent a default, and a caller reading it
+         * to name a base needs to see that it has to ask the provider rather than assume `main`.
+         */
+        readonly defaultBranch: v.StringSchema<undefined>;
+        /** Whether the repository is private on its provider. */
+        readonly private: v.BooleanSchema<undefined>;
+        /** Whether the repo is flagged as hosting several services (see `repo.monorepo`). */
+        readonly monorepo: v.BooleanSchema<undefined>;
+        /**
+         * The service this repository already backs ON THIS BOARD, or null.
+         *
+         * Present because a whole-repo repository backs at most ONE service, so a caller choosing one to
+         * create against needs to know which choices are already spent, and, more usefully, because a
+         * caller re-running its provisioning finds the service it created last time here rather than
+         * discovering it through a `409`. A monorepo answers null even when its subdirectories back
+         * services, since it can back more.
+         *
+         * Null and {@link linkedElsewhere} together are the honest answer when the service is homed on
+         * another board of the account: read the flag before treating null as "available".
+         */
+        readonly serviceId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * True when this repository already backs a whole-repo service homed on ANOTHER board of the
+         * account, so `POST /api/v1/services` will refuse it (`reason: repo_service_homed_elsewhere`).
+         *
+         * A service is account-owned and a board can MOUNT one homed elsewhere, but every read on this
+         * API is scoped to the calling key's own workspace, so a frame homed on another board has no id
+         * this surface could hand back: it would not appear in `GET /api/v1/services` and
+         * `POST /api/v1/services/{serviceId}/tasks` would 404 on it. Hence a flag rather than a second
+         * id field — this states that the choice is spent without naming an address that does not work
+         * here. Use the board that homes the service, or a key scoped to it.
+         */
+        readonly linkedElsewhere: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type PublicRepoList = v.InferOutput<typeof publicRepoListSchema>;
+/**
+ * Declare that a task must wait for another one.
+ *
+ * The gap it closes: an integration filing five related tasks and starting them got five runs
+ * racing against one repository, each opening a pull request against a base the others were
+ * moving. The platform has had the mechanism to serialise them (the engine's start gate refuses a
+ * task whose blockers are not `done`, and `autoStartDependents` starts a task when its blocker
+ * merges) and no way for an external caller to be told about it.
+ *
+ * The edge is stored on the DEPENDENT: `POST /api/v1/tasks/{taskId}/dependencies` says "this task
+ * waits for `dependsOnTaskId`". Both ends must be tasks (only a task ever reaches `done`, so an
+ * edge onto a service or a module would wedge the run's start gate forever), and an edge that would
+ * close a cycle is refused, so the gate and the auto-start can never deadlock.
+ */
+export declare const publicTaskDependencySchema: v.ObjectSchema<{
+    /** The task that must finish first. Must be a task in the same workspace, and not this one. */
+    readonly dependsOnTaskId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+}, undefined>;
+export type PublicTaskDependencyInput = v.InferOutput<typeof publicTaskDependencySchema>;
+/**
+ * A document attached to a task as agent context, as the task's document list serves it.
+ *
+ * Identified by `(source, externalId)` rather than by an id of its own, because that pair IS a
+ * projected document's identity: a re-import of the same page lands on the same row, which is what
+ * makes attaching one idempotent. `source` is `upload` for a body a caller carried rather than
+ * named, and such a document has no page behind it, which is why `url` is empty there rather than
+ * absent.
+ */
+export declare const publicAttachedDocumentSchema: v.ObjectSchema<{
+    /** Which source the document came from, or `upload` for one a caller carried inline. */
+    readonly source: v.PicklistSchema<["confluence", "notion", "github", "figma", "zeplin", "linear", "upload"], undefined>;
+    /** The source's stable id for the page: the value to pass back to detach it. */
+    readonly externalId: v.StringSchema<undefined>;
+    readonly title: v.StringSchema<undefined>;
+    /** Canonical URL on the source; EMPTY for an `upload`, which has no page to link back to. */
+    readonly url: v.StringSchema<undefined>;
+    /** A short plain-text excerpt of the body (the full text reaches the run, not this list). */
+    readonly excerpt: v.StringSchema<undefined>;
+}, undefined>;
+export type PublicAttachedDocument = v.InferOutput<typeof publicAttachedDocumentSchema>;
+export declare const publicAttachedDocumentListSchema: v.ObjectSchema<{
+    readonly documents: v.ArraySchema<v.ObjectSchema<{
+        /** Which source the document came from, or `upload` for one a caller carried inline. */
+        readonly source: v.PicklistSchema<["confluence", "notion", "github", "figma", "zeplin", "linear", "upload"], undefined>;
+        /** The source's stable id for the page: the value to pass back to detach it. */
+        readonly externalId: v.StringSchema<undefined>;
+        readonly title: v.StringSchema<undefined>;
+        /** Canonical URL on the source; EMPTY for an `upload`, which has no page to link back to. */
+        readonly url: v.StringSchema<undefined>;
+        /** A short plain-text excerpt of the body (the full text reaches the run, not this list). */
+        readonly excerpt: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type PublicAttachedDocumentList = v.InferOutput<typeof publicAttachedDocumentListSchema>;
+/**
+ * Attach a requirements document to a task that already exists.
+ *
+ * The same two forms creation takes ({@link publicTaskDocumentSchema}): NAME a page in a connected
+ * document source, or CARRY the text. What it adds is the moment: a task's spec routinely arrives
+ * after the task does (a ticket filed first and specified later, a PRD that lands mid-review), and
+ * until this existed the only way to attach one was to delete the task and file it again, losing
+ * the id every stored reference points at, its ticket claim (which then refuses every future filing
+ * of that ticket) and the documents it already carried.
+ *
+ * A document a DIFFERENT live task already holds is refused rather than moved: a document row
+ * carries exactly one attachment, so moving it would strip the other task of a document it was
+ * created with, with nothing in its next run reporting the absence.
+ */
+export declare const attachPublicTaskDocumentSchema: v.ObjectSchema<{
+    readonly document: v.VariantSchema<"kind", [v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"source", undefined>;
+        readonly source: v.PicklistSchema<["confluence", "notion", "github", "figma", "zeplin", "linear"], undefined>;
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"upload", undefined>;
+        readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+        readonly content: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 100000, undefined>]>;
+    }, undefined>], undefined>;
+}, undefined>;
+export type AttachPublicTaskDocumentInput = v.InferOutput<typeof attachPublicTaskDocumentSchema>;
+/**
+ * Detach a document from a task, naming it by the `(source, externalId)` pair the task's document
+ * list serves.
+ *
+ * A POST with a body rather than a `DELETE .../documents/{id}`, because a document's identity is
+ * two values and one of them is a free-form external id: a Confluence page id is fine in a path
+ * segment and a GitHub docs path (`docs/architecture/adr-0001.md`) is not, so half the sources
+ * would need escaping rules a caller has to get right to address its own document.
+ *
+ * The document itself SURVIVES: it stays in the workspace exactly as the app's own detach leaves
+ * it, so re-attaching it costs no re-import. Idempotent: detaching a document this task does not
+ * hold is a no-op rather than an error, because a caller retrying after a timeout should converge
+ * rather than have to distinguish "it was never attached" from "I already detached it".
+ */
+export declare const detachPublicTaskDocumentSchema: v.ObjectSchema<{
+    readonly source: v.PicklistSchema<["confluence", "notion", "github", "figma", "zeplin", "linear", "upload"], undefined>;
+    readonly externalId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+}, undefined>;
+export type DetachPublicTaskDocumentInput = v.InferOutput<typeof detachPublicTaskDocumentSchema>;
+//# sourceMappingURL=public-board.d.ts.map

package/dist/public-board.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-board.d.ts","sourceRoot":"","sources":["../src/public-board.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AA8B5B;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;IAClC,wDAAwD;;IAExD;;;;;OAKG;;IAEH;;;;OAIG;;aAEH,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;IACpC;;;;OAIG;;IAEH,iGAAiG;;IAEjG;;;;;;OAMG;;IAEH,mFAAmF;;QA9CnF,wDAAwD;;QAExD;;;;;WAKG;;QAEH;;;;WAIG;;;aAmCH,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEtF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;IAC3B,0EAA0E;;IAE1E,wDAAwD;;;;IAIxD;;;;;OAKG;;IAEH,yDAAyD;;IAEzD,qFAAqF;;IAErF;;;;;;;;;;;OAWG;;IAEH;;;;;;;;;;OAUG;;aAEH,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D,eAAO,MAAM,oBAAoB;;QA7C/B,0EAA0E;;QAE1E,wDAAwD;;;;QAIxD;;;;;WAKG;;QAEH,yDAAyD;;QAEzD,qFAAqF;;QAErF;;;;;;;;;;;WAWG;;QAEH;;;;;;;;;;WAUG;;;aAK6E,CAAA;AAClF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0BAA0B;IACrC,+FAA+F;;aAE/F,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAExF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;IACvC,wFAAwF;;IAExF,gFAAgF;;;IAGhF,6FAA6F;;IAE7F,6FAA6F;;aAE7F,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF,eAAO,MAAM,gCAAgC;;QAZ3C,wFAAwF;;QAExF,gFAAgF;;;QAGhF,6FAA6F;;QAE7F,6FAA6F;;;aAO7F,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,gCAAgC,CAAC,CAAA;AAE/F;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;aAEzC,CAAA;AACF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAA;AAEhG;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B;;;aAGzC,CAAA;AACF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAA"}

package/dist/public-board.js

@@ -0,0 +1,215 @@
+import * as v from 'valibot';
+import { documentOriginSchema } from './documents.js';
+import { frameRepoTypeSchema } from './primitives.js';
+import { publicTaskDocumentSchema } from './public-api.js';
+// ---------------------------------------------------------------------------
+// Public-API wire contracts for PROVISIONING the board a headless deployment drives, and for
+// the two task relationships that outlive a single create call.
+//
+// `/api/v1` could list services and create a task under one, and nothing could create a service,
+// link a repository to one, express an ordering between two tasks, or change a task's attached
+// documents after it was filed. That is the same class of gap the outbound webhook and headless key
+// provisioning each closed for themselves: a deployment whose operator is headless could drive
+// every part of this API except the one act it had to open a browser for.
+//
+// Three rules shape everything here, and each is a boundary rather than a preference:
+//
+//  1. **No board COORDINATES.** Positions, sizes and reparenting are ergonomics for a human looking
+//     at a canvas. Publishing a coordinate system into a surface that is frozen forever buys an
+//     integration nothing and costs the board its freedom to change how it lays itself out, so a
+//     service created here is laid out by the platform exactly as the app's own import button
+//     lays one out.
+//  2. **The REPO LINK is the load-bearing half.** A service frame with no linked repository cannot
+//     run anything (`resolveRepoTarget` throws by design, deliberately with no first-repo
+//     fallback), so an endpoint that created frames and could not link them would ship output
+//     that is unusable by the very surface that made it.
+//  3. **One rule at every door.** Every write here delegates to the SAME service method the SPA's
+//     own controller calls, so an invariant cannot differ by surface.
+// ---------------------------------------------------------------------------
+/**
+ * The repository a new service frame is backed by.
+ *
+ * `repoId` is the provider's own id for the repo, as `GET /api/v1/repos` serves it: the neutral
+ * name for what the internal projection calls `githubId`. It is deliberately not an `owner/name`
+ * pair: a repo can be renamed or transferred without changing its id, and a caller that held a name
+ * would silently create a service against a different repository after such a move.
+ */
+export const publicServiceRepoSchema = v.object({
+    /** The repo's provider id, from `GET /api/v1/repos`. */
+    repoId: v.number(),
+    /**
+     * For a MONOREPO, the subdirectory (relative to the repo root) this service lives in, e.g.
+     * `packages/api`. Required when the repo is a monorepo and refused for a whole-repo service,
+     * because it is what scopes each agent's working directory: a monorepo backs one service per
+     * subdirectory, and two services claiming the same one would fight over the same subtree.
+     */
+    directory: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(400))),
+    /**
+     * Whether the repository hosts SEVERAL services. Sent with the create rather than as a separate
+     * up-front write; when supplied it is persisted on the repo, so the flag a later create reads is
+     * the one this call set. Omitted ⇒ whatever the repo already says.
+     */
+    monorepo: v.optional(v.boolean()),
+});
+/**
+ * Create a board service (a service frame), optionally backed by a repository.
+ *
+ * Without `repo` the frame is a structural placeholder: it can hold tasks, and a run started on one
+ * of them is REFUSED, because execution resolves a task's repository by walking up to the enclosing
+ * service frame and there is nothing there. That is a legitimate intermediate state (a caller
+ * mapping out a board before its repositories exist) and it is why the field is optional rather
+ * than why it should usually be omitted.
+ *
+ * There is deliberately no `position`: see the note at the top of this file.
+ */
+export const createPublicServiceSchema = v.object({
+    /**
+     * The service's name. Optional, because a repo-backed service is named after the repository (or,
+     * for a monorepo service, after its subdirectory) exactly as the app's import does, and a caller
+     * that has no better name should get that one rather than being made to invent it.
+     */
+    title: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200))),
+    /** What the service is, for the agents that read it as context. Defaults to a generated line. */
+    description: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(2000))),
+    /**
+     * The service's architectural role. Omitted ⇒ `service`.
+     *
+     * Narrower than the board's own block types on purpose: this is the set a REPOSITORY can back,
+     * which is the only kind of frame this endpoint creates. A `database` or `queue` frame documents
+     * infrastructure for the agents to read and runs nothing, so nothing here would create one.
+     */
+    type: v.optional(frameRepoTypeSchema),
+    /** The repository backing the service. Omitted ⇒ an unlinked frame (see above). */
+    repo: v.optional(publicServiceRepoSchema),
+});
+/**
+ * A repository this workspace can back a service with, as `GET /api/v1/repos` lists it.
+ *
+ * The discovery half of {@link publicServiceRepoSchema}, and it is why service creation is usable
+ * headlessly at all: the create takes a `repoId`, and until this existed the only way to learn one
+ * was to open the app. Deliberately a small projection (enough to recognise a repository and pass
+ * it back), not a mirror of the internal projection row, which carries installation ids and
+ * sync bookkeeping that are this platform's business rather than a caller's.
+ */
+export const publicRepoSchema = v.object({
+    /** The provider's id for the repo: the value to pass as `repo.repoId`. */
+    repoId: v.number(),
+    /** Which provider it lives on (`github` / `gitlab`). */
+    provider: v.string(),
+    owner: v.string(),
+    name: v.string(),
+    /**
+     * The branch a run's work is based on and merged into, or EMPTY when the projection has not
+     * recorded one yet (a repository connected moments ago, before its first sync). Empty rather
+     * than null because there is nothing here that could invent a default, and a caller reading it
+     * to name a base needs to see that it has to ask the provider rather than assume `main`.
+     */
+    defaultBranch: v.string(),
+    /** Whether the repository is private on its provider. */
+    private: v.boolean(),
+    /** Whether the repo is flagged as hosting several services (see `repo.monorepo`). */
+    monorepo: v.boolean(),
+    /**
+     * The service this repository already backs ON THIS BOARD, or null.
+     *
+     * Present because a whole-repo repository backs at most ONE service, so a caller choosing one to
+     * create against needs to know which choices are already spent, and, more usefully, because a
+     * caller re-running its provisioning finds the service it created last time here rather than
+     * discovering it through a `409`. A monorepo answers null even when its subdirectories back
+     * services, since it can back more.
+     *
+     * Null and {@link linkedElsewhere} together are the honest answer when the service is homed on
+     * another board of the account: read the flag before treating null as "available".
+     */
+    serviceId: v.nullable(v.string()),
+    /**
+     * True when this repository already backs a whole-repo service homed on ANOTHER board of the
+     * account, so `POST /api/v1/services` will refuse it (`reason: repo_service_homed_elsewhere`).
+     *
+     * A service is account-owned and a board can MOUNT one homed elsewhere, but every read on this
+     * API is scoped to the calling key's own workspace, so a frame homed on another board has no id
+     * this surface could hand back: it would not appear in `GET /api/v1/services` and
+     * `POST /api/v1/services/{serviceId}/tasks` would 404 on it. Hence a flag rather than a second
+     * id field — this states that the choice is spent without naming an address that does not work
+     * here. Use the board that homes the service, or a key scoped to it.
+     */
+    linkedElsewhere: v.boolean(),
+});
+export const publicRepoListSchema = v.object({ repos: v.array(publicRepoSchema) });
+/**
+ * Declare that a task must wait for another one.
+ *
+ * The gap it closes: an integration filing five related tasks and starting them got five runs
+ * racing against one repository, each opening a pull request against a base the others were
+ * moving. The platform has had the mechanism to serialise them (the engine's start gate refuses a
+ * task whose blockers are not `done`, and `autoStartDependents` starts a task when its blocker
+ * merges) and no way for an external caller to be told about it.
+ *
+ * The edge is stored on the DEPENDENT: `POST /api/v1/tasks/{taskId}/dependencies` says "this task
+ * waits for `dependsOnTaskId`". Both ends must be tasks (only a task ever reaches `done`, so an
+ * edge onto a service or a module would wedge the run's start gate forever), and an edge that would
+ * close a cycle is refused, so the gate and the auto-start can never deadlock.
+ */
+export const publicTaskDependencySchema = v.object({
+    /** The task that must finish first. Must be a task in the same workspace, and not this one. */
+    dependsOnTaskId: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(120)),
+});
+/**
+ * A document attached to a task as agent context, as the task's document list serves it.
+ *
+ * Identified by `(source, externalId)` rather than by an id of its own, because that pair IS a
+ * projected document's identity: a re-import of the same page lands on the same row, which is what
+ * makes attaching one idempotent. `source` is `upload` for a body a caller carried rather than
+ * named, and such a document has no page behind it, which is why `url` is empty there rather than
+ * absent.
+ */
+export const publicAttachedDocumentSchema = v.object({
+    /** Which source the document came from, or `upload` for one a caller carried inline. */
+    source: documentOriginSchema,
+    /** The source's stable id for the page: the value to pass back to detach it. */
+    externalId: v.string(),
+    title: v.string(),
+    /** Canonical URL on the source; EMPTY for an `upload`, which has no page to link back to. */
+    url: v.string(),
+    /** A short plain-text excerpt of the body (the full text reaches the run, not this list). */
+    excerpt: v.string(),
+});
+export const publicAttachedDocumentListSchema = v.object({
+    documents: v.array(publicAttachedDocumentSchema),
+});
+/**
+ * Attach a requirements document to a task that already exists.
+ *
+ * The same two forms creation takes ({@link publicTaskDocumentSchema}): NAME a page in a connected
+ * document source, or CARRY the text. What it adds is the moment: a task's spec routinely arrives
+ * after the task does (a ticket filed first and specified later, a PRD that lands mid-review), and
+ * until this existed the only way to attach one was to delete the task and file it again, losing
+ * the id every stored reference points at, its ticket claim (which then refuses every future filing
+ * of that ticket) and the documents it already carried.
+ *
+ * A document a DIFFERENT live task already holds is refused rather than moved: a document row
+ * carries exactly one attachment, so moving it would strip the other task of a document it was
+ * created with, with nothing in its next run reporting the absence.
+ */
+export const attachPublicTaskDocumentSchema = v.object({
+    document: publicTaskDocumentSchema,
+});
+/**
+ * Detach a document from a task, naming it by the `(source, externalId)` pair the task's document
+ * list serves.
+ *
+ * A POST with a body rather than a `DELETE .../documents/{id}`, because a document's identity is
+ * two values and one of them is a free-form external id: a Confluence page id is fine in a path
+ * segment and a GitHub docs path (`docs/architecture/adr-0001.md`) is not, so half the sources
+ * would need escaping rules a caller has to get right to address its own document.
+ *
+ * The document itself SURVIVES: it stays in the workspace exactly as the app's own detach leaves
+ * it, so re-attaching it costs no re-import. Idempotent: detaching a document this task does not
+ * hold is a no-op rather than an error, because a caller retrying after a timeout should converge
+ * rather than have to distinguish "it was never attached" from "I already detached it".
+ */
+export const detachPublicTaskDocumentSchema = v.object({
+    source: documentOriginSchema,
+    externalId: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(500)),
+});
+//# sourceMappingURL=public-board.js.map

package/dist/public-board.js.map

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

package/dist/public-evidence.d.ts

@@ -6,11 +6,30 @@ import * as v from 'valibot';
  */
 export declare const publicArtifactKindSchema: v.PicklistSchema<["screenshot", "reference"], undefined>;
 export type PublicArtifactKind = v.InferOutput<typeof publicArtifactKindSchema>;
+/**
+ * What an artifact is ANCHORED on, which is what says whether the run produced it:
+ *
+ * - `run`: captured by THIS run. It carries the run's id, and a re-run captures its own.
+ * - `task`: attached to the run's task and outliving any single run of it. A reference design a
+ *   person uploaded before the first run is the case that matters: it is what the run's
+ *   screenshots are judged against, and it is deliberately not run-anchored, because uploading one
+ *   per attempt is exactly what a reference exists to avoid.
+ *
+ * Stated per row rather than folded away, because the two sets answer different questions and a
+ * silent union would make "the run captured 3 screenshots" unreadable off a list of 5. It is also
+ * why the list is not simply the run's own rows: a caller enumerating a run's artifacts to compare
+ * a screenshot against its reference saw only one half, so the reference rendered as ABSENT on the
+ * one surface whose job is to say what a run proved, while being individually fetchable all along.
+ */
+export declare const publicArtifactScopeSchema: v.PicklistSchema<["run", "task"], undefined>;
+export type PublicArtifactScope = v.InferOutput<typeof publicArtifactScopeSchema>;
 /** One binary artifact a run produced (metadata; the bytes are a separate fetch). */
 export declare const publicRunArtifactSchema: v.ObjectSchema<{
     /** The id to pass to `GET /api/v1/artifacts/{artifactId}/blob`. */
     readonly artifactId: v.StringSchema<undefined>;
     readonly kind: v.PicklistSchema<["screenshot", "reference"], undefined>;
+    /** Which anchor this row came from ({@link publicArtifactScopeSchema}). */
+    readonly scope: v.PicklistSchema<["run", "task"], undefined>;
     /** Logical view name, which is what pairs a screenshot with its reference. Null when unnamed. */
     readonly view: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     /** The MIME type the blob endpoint will answer with (always a raster image today). */
@@ -26,17 +45,25 @@ export declare const publicRunArtifactSchema: v.ObjectSchema<{
 }, undefined>;
 export type PublicRunArtifact = v.InferOutput<typeof publicRunArtifactSchema>;
 /**
- * A run's artifacts, whole rather than paginated.
+ * A run's artifacts (the ones it CAPTURED plus the ones attached to its task, each saying which
+ * it is: {@link publicArtifactScopeSchema}), whole rather than paginated.
  *
  * Deliberately unpaged where every sibling list is keyset-paginated: the capture path enforces
- * a per-run ceiling, so the row count is bounded by construction and the response size is
- * computable before the request. A cursor here would be a page-2 that structurally cannot exist.
+ * a per-run ceiling and a task's uploads are a human-sized set, so the row count is bounded by
+ * construction and the response size is computable before the request. A cursor here would be a
+ * page-2 that structurally cannot exist.
+ *
+ * An artifact that is BOTH (a screenshot a run captured against its own task) appears ONCE, as
+ * `run`: the run is the more specific anchor, and a row appearing twice under two scopes would
+ * make every count off this list wrong in the direction that reads as extra evidence.
  */
 export declare const publicRunArtifactListSchema: v.ObjectSchema<{
     readonly artifacts: v.ArraySchema<v.ObjectSchema<{
         /** The id to pass to `GET /api/v1/artifacts/{artifactId}/blob`. */
         readonly artifactId: v.StringSchema<undefined>;
         readonly kind: v.PicklistSchema<["screenshot", "reference"], undefined>;
+        /** Which anchor this row came from ({@link publicArtifactScopeSchema}). */
+        readonly scope: v.PicklistSchema<["run", "task"], undefined>;
         /** Logical view name, which is what pairs a screenshot with its reference. Null when unnamed. */
         readonly view: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         /** The MIME type the blob endpoint will answer with (always a raster image today). */

package/dist/public-evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public-evidence.d.ts","sourceRoot":"","sources":["../src/public-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AA0B5B;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,0DAA0C,CAAA;AAC/E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E,qFAAqF;AACrF,eAAO,MAAM,uBAAuB;IAClC,mEAAmE;;;IAGnE,iGAAiG;;IAEjG,sFAAsF;;IAEtF;;;OAGG;;IAEH,0FAA0F;;;aAG1F,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;QAzBtC,mEAAmE;;;QAGnE,iGAAiG;;QAEjG,sFAAsF;;QAEtF;;;WAGG;;QAEH,0FAA0F;;;;aAe1F,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA"}
+{"version":3,"file":"public-evidence.d.ts","sourceRoot":"","sources":["../src/public-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AA0B5B;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,0DAA0C,CAAA;AAC/E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,8CAA8B,CAAA;AACpE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF,qFAAqF;AACrF,eAAO,MAAM,uBAAuB;IAClC,mEAAmE;;;IAGnE,2EAA2E;;IAE3E,iGAAiG;;IAEjG,sFAAsF;;IAEtF;;;OAGG;;IAEH,0FAA0F;;;aAG1F,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B;;QAjCtC,mEAAmE;;;QAGnE,2EAA2E;;QAE3E,iGAAiG;;QAEjG,sFAAsF;;QAEtF;;;WAGG;;QAEH,0FAA0F;;;;aAqB1F,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA"}

package/dist/public-evidence.js

@@ -28,11 +28,29 @@ import * as v from 'valibot';
  * human uploaded for the run to be judged against.
  */
 export const publicArtifactKindSchema = v.picklist(['screenshot', 'reference']);
+/**
+ * What an artifact is ANCHORED on, which is what says whether the run produced it:
+ *
+ * - `run`: captured by THIS run. It carries the run's id, and a re-run captures its own.
+ * - `task`: attached to the run's task and outliving any single run of it. A reference design a
+ *   person uploaded before the first run is the case that matters: it is what the run's
+ *   screenshots are judged against, and it is deliberately not run-anchored, because uploading one
+ *   per attempt is exactly what a reference exists to avoid.
+ *
+ * Stated per row rather than folded away, because the two sets answer different questions and a
+ * silent union would make "the run captured 3 screenshots" unreadable off a list of 5. It is also
+ * why the list is not simply the run's own rows: a caller enumerating a run's artifacts to compare
+ * a screenshot against its reference saw only one half, so the reference rendered as ABSENT on the
+ * one surface whose job is to say what a run proved, while being individually fetchable all along.
+ */
+export const publicArtifactScopeSchema = v.picklist(['run', 'task']);
 /** One binary artifact a run produced (metadata; the bytes are a separate fetch). */
 export const publicRunArtifactSchema = v.object({
     /** The id to pass to `GET /api/v1/artifacts/{artifactId}/blob`. */
     artifactId: v.string(),
     kind: publicArtifactKindSchema,
+    /** Which anchor this row came from ({@link publicArtifactScopeSchema}). */
+    scope: publicArtifactScopeSchema,
     /** Logical view name, which is what pairs a screenshot with its reference. Null when unnamed. */
     view: v.nullable(v.string()),
     /** The MIME type the blob endpoint will answer with (always a raster image today). */
@@ -47,11 +65,17 @@ export const publicRunArtifactSchema = v.object({
     createdAt: v.number(),
 });
 /**
- * A run's artifacts, whole rather than paginated.
+ * A run's artifacts (the ones it CAPTURED plus the ones attached to its task, each saying which
+ * it is: {@link publicArtifactScopeSchema}), whole rather than paginated.
  *
  * Deliberately unpaged where every sibling list is keyset-paginated: the capture path enforces
- * a per-run ceiling, so the row count is bounded by construction and the response size is
- * computable before the request. A cursor here would be a page-2 that structurally cannot exist.
+ * a per-run ceiling and a task's uploads are a human-sized set, so the row count is bounded by
+ * construction and the response size is computable before the request. A cursor here would be a
+ * page-2 that structurally cannot exist.
+ *
+ * An artifact that is BOTH (a screenshot a run captured against its own task) appears ONCE, as
+ * `run`: the run is the more specific anchor, and a row appearing twice under two scopes would
+ * make every count off this list wrong in the direction that reads as extra evidence.
  */
 export const publicRunArtifactListSchema = v.object({
     artifacts: v.array(publicRunArtifactSchema),

package/dist/public-evidence.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-evidence.js","sourceRoot":"","sources":["../src/public-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,wFAAwF;AACxF,kDAAkD;AAClD,EAAE;AACF,2FAA2F;AAC3F,wFAAwF;AACxF,uFAAuF;AACvF,wFAAwF;AACxF,0FAA0F;AAC1F,oBAAoB;AACpB,EAAE;AACF,6CAA6C;AAC7C,EAAE;AACF,6FAA6F;AAC7F,6FAA6F;AAC7F,uFAAuF;AACvF,0FAA0F;AAC1F,yEAAyE;AACzE,yFAAyF;AACzF,8FAA8F;AAC9F,4FAA4F;AAC5F,mEAAmE;AACnE,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAAA;AAG/E,qFAAqF;AACrF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,mEAAmE;IACnE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,IAAI,EAAE,wBAAwB;IAC9B,iGAAiG;IACjG,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC5B,sFAAsF;IACtF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,0FAA0F;IAC1F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAA;AAGF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;CAC5C,CAAC,CAAA"}
+{"version":3,"file":"public-evidence.js","sourceRoot":"","sources":["../src/public-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,wFAAwF;AACxF,kDAAkD;AAClD,EAAE;AACF,2FAA2F;AAC3F,wFAAwF;AACxF,uFAAuF;AACvF,wFAAwF;AACxF,0FAA0F;AAC1F,oBAAoB;AACpB,EAAE;AACF,6CAA6C;AAC7C,EAAE;AACF,6FAA6F;AAC7F,6FAA6F;AAC7F,uFAAuF;AACvF,0FAA0F;AAC1F,yEAAyE;AACzE,yFAAyF;AACzF,8FAA8F;AAC9F,4FAA4F;AAC5F,mEAAmE;AACnE,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAAA;AAG/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;AAGpE,qFAAqF;AACrF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,mEAAmE;IACnE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,IAAI,EAAE,wBAAwB;IAC9B,2EAA2E;IAC3E,KAAK,EAAE,yBAAyB;IAChC,iGAAiG;IACjG,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC5B,sFAAsF;IACtF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,0FAA0F;IAC1F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAA;AAGF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;CAC5C,CAAC,CAAA"}