@cat-factory/contracts 0.6.0

package/dist/environments.js

@@ -0,0 +1,190 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// Ephemeral environment provider wire contracts. Every organization rolls its
+// own preview/ephemeral-env tooling with bespoke internal auth, so rather than
+// integrating against a fixed SaaS we let an org describe its *own* HTTP-based
+// management API declaratively: a manifest of request templates for
+// provision/status/teardown, the auth scheme for calling it, and a mapping from
+// that API's (arbitrary) response shape onto a canonical environment handle.
+//
+// A single generic adapter in the worker interprets any manifest — there are no
+// per-provider presets and no per-org code. After a "deployer" step provisions
+// an environment, the resulting handle is surfaced to downstream tester agents
+// so they can run against the live URL.
+//
+// Secret handling: the manifest references credentials by *logical key* only —
+// never values. The actual per-tenant secret values are supplied separately at
+// registration, stored encrypted-at-rest in D1, and resolved in-memory at call
+// time. Nothing here ever carries a raw secret on the wire.
+// ---------------------------------------------------------------------------
+/**
+ * A reference to a credential by logical key. Resolves against the workspace's
+ * encrypted secret bundle (supplied at registration), not an env var.
+ */
+export const environmentSecretRefSchema = v.object({
+    key: v.pipe(v.string(), v.regex(/^[A-Za-z0-9_.-]+$/), v.minLength(1), v.maxLength(64)),
+});
+const nonEmpty = v.pipe(v.string(), v.minLength(1));
+const urlString = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(2000));
+/**
+ * How the worker authenticates to the org's *management* API (the one we call to
+ * provision/status/teardown). Covers the common schemes; each references its
+ * secret(s) by logical key.
+ */
+export const environmentAuthSchemeSchema = v.variant('type', [
+    v.object({ type: v.literal('none') }),
+    v.object({
+        type: v.literal('api_key'),
+        headerName: nonEmpty,
+        secretRef: environmentSecretRefSchema,
+        /** Optional prefix prepended to the secret value, e.g. `Token `. */
+        valuePrefix: v.optional(v.string()),
+    }),
+    v.object({ type: v.literal('bearer'), secretRef: environmentSecretRefSchema }),
+    v.object({
+        type: v.literal('basic'),
+        usernameSecretRef: environmentSecretRefSchema,
+        passwordSecretRef: environmentSecretRefSchema,
+    }),
+    v.object({
+        type: v.literal('oauth2_client_credentials'),
+        tokenUrl: urlString,
+        clientIdSecretRef: environmentSecretRefSchema,
+        clientSecretSecretRef: environmentSecretRefSchema,
+        scope: v.optional(v.string()),
+        audience: v.optional(v.string()),
+    }),
+    v.object({
+        type: v.literal('custom_headers'),
+        headers: v.array(v.object({ name: nonEmpty, secretRef: environmentSecretRefSchema })),
+    }),
+]);
+export const environmentHttpMethodSchema = v.picklist(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+/**
+ * One HTTP call against the management API. Fully generic: any method, an
+ * arbitrary path appended to the manifest `baseUrl`, optional query/headers and
+ * a body, all supporting `{{var}}` interpolation. Variables come from a bounded
+ * namespace: `{{input.*}}` (provision inputs) and `{{provision.*}}` (fields
+ * extracted from an earlier provision response, available to status/teardown).
+ */
+export const environmentRequestTemplateSchema = v.object({
+    method: environmentHttpMethodSchema,
+    pathTemplate: v.pipe(v.string(), v.maxLength(2000)),
+    query: v.optional(v.array(v.object({ key: v.string(), value: v.string() }))),
+    headers: v.optional(v.array(v.object({ name: nonEmpty, value: v.string() }))),
+    bodyTemplate: v.optional(v.string()),
+    /** Per-call timeout (ms). Bounded; defaults applied by the adapter. */
+    timeoutMs: v.optional(v.pipe(v.number(), v.minValue(1), v.maxValue(60000))),
+});
+/** The lifecycle states a provisioned environment moves through. */
+export const environmentStatusSchema = v.picklist([
+    'provisioning',
+    'ready',
+    'failed',
+    'expired',
+    'tearing_down',
+    'torn_down',
+]);
+export const environmentAccessSchemeSchema = v.picklist([
+    'none',
+    'bearer',
+    'basic',
+    'custom_header',
+]);
+/**
+ * How to read the *provisioned environment's own* access credentials out of the
+ * management API's response. These are per-environment, ephemeral creds the
+ * tester uses to reach the env — distinct from the management-API auth above.
+ */
+export const environmentAccessMappingSchema = v.object({
+    scheme: environmentAccessSchemeSchema,
+    tokenPath: v.optional(v.string()),
+    usernamePath: v.optional(v.string()),
+    passwordPath: v.optional(v.string()),
+    headerName: v.optional(v.string()),
+    headerValuePath: v.optional(v.string()),
+});
+/**
+ * Maps an arbitrary self-rolled response onto the canonical handle via dot-path
+ * field extraction (e.g. `data.url`). `statusMap` translates the provider's own
+ * status strings onto our lifecycle states.
+ */
+export const environmentResponseMappingSchema = v.object({
+    urlPath: v.optional(v.string()),
+    statusPath: v.optional(v.string()),
+    statusMap: v.optional(v.array(v.object({ from: v.string(), to: environmentStatusSchema }))),
+    expiresAtPath: v.optional(v.string()),
+    externalIdPath: v.optional(v.string()),
+    access: v.optional(environmentAccessMappingSchema),
+});
+/** The full declarative description of an org's ephemeral-env management API. */
+export const environmentManifestSchema = v.object({
+    providerId: v.pipe(v.string(), v.regex(/^[a-z0-9-]+$/), v.minLength(1), v.maxLength(64)),
+    label: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(120)),
+    /** Management API root; provision/status/teardown paths are appended to it. */
+    baseUrl: urlString,
+    auth: environmentAuthSchemeSchema,
+    provision: environmentRequestTemplateSchema,
+    /** Optional: polled to observe async provisioning progress. */
+    status: v.optional(environmentRequestTemplateSchema),
+    /** Optional: called to destroy the environment (manual or on TTL expiry). */
+    teardown: v.optional(environmentRequestTemplateSchema),
+    response: environmentResponseMappingSchema,
+    /** Fallback TTL (ms) when the response carries no explicit expiry. */
+    defaultTtlMs: v.optional(v.pipe(v.number(), v.minValue(60000))),
+});
+/** Resolved access creds for a provisioned env, as surfaced to a tester agent. */
+export const environmentAccessHandleSchema = v.object({
+    scheme: environmentAccessSchemeSchema,
+    token: v.optional(v.string()),
+    username: v.optional(v.string()),
+    password: v.optional(v.string()),
+    headerName: v.optional(v.string()),
+    headerValue: v.optional(v.string()),
+});
+/** A provisioned environment, as exposed to clients and downstream agents. */
+export const environmentHandleSchema = v.object({
+    id: v.string(),
+    workspaceId: v.string(),
+    blockId: v.nullable(v.string()),
+    executionId: v.nullable(v.string()),
+    providerId: v.string(),
+    externalId: v.nullable(v.string()),
+    url: v.nullable(v.string()),
+    status: environmentStatusSchema,
+    /** Present only on the dedicated access endpoint / in agent context. */
+    access: v.optional(environmentAccessHandleSchema),
+    createdAt: v.number(),
+    expiresAt: v.nullable(v.number()),
+    lastError: v.nullable(v.string()),
+});
+/** A workspace's provider binding, as exposed to clients (never secret values). */
+export const environmentConnectionSchema = v.object({
+    providerId: v.string(),
+    label: v.string(),
+    baseUrl: v.string(),
+    connectedAt: v.number(),
+    /** Which secret keys are set (names only), so the UI can show completeness. */
+    secretKeys: v.array(v.string()),
+});
+// ---- Request bodies -------------------------------------------------------
+/**
+ * Register (or replace) a workspace's environment provider. The org supplies the
+ * actual per-tenant secret values here (write-only); they are encrypted and
+ * stored in D1 and never returned. Every `secretRef.key` in the manifest must
+ * have a matching entry in `secrets`.
+ */
+export const registerEnvironmentProviderSchema = v.object({
+    manifest: environmentManifestSchema,
+    secrets: v.record(v.string(), v.string()),
+});
+/** Rotate/replace the per-tenant secret bundle without re-sending the manifest. */
+export const updateEnvironmentSecretsSchema = v.object({
+    secrets: v.record(v.string(), v.string()),
+});
+/** Manually provision an environment (outside a pipeline run). */
+export const provisionEnvironmentSchema = v.object({
+    blockId: v.optional(v.pipe(v.string(), v.minLength(1))),
+    inputs: v.optional(v.record(v.string(), v.string())),
+});
+//# sourceMappingURL=environments.js.map

package/dist/environments.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,98 @@
+import type { Block, ExecutionInstance } from './entities.js';
+import type { BootstrapJob } from './bootstrap.js';
+import type { Notification } from './notifications.js';
+import type { LlmCallActivity } from './observability.js';
+import type { RequirementReview } from './requirements.js';
+import type { ConsensusSession } from './consensus.js';
+import type { ClarityReview } from './clarity.js';
+export type WorkspaceEvent = 
+/**
+ * A run advanced. Carries the updated instance and its server-rolled block, so
+ * the client patches both caches without a refetch. `block` is null only if the
+ * block vanished between the transition and the publish.
+ */
+{
+    type: 'execution';
+    instance: ExecutionInstance;
+    block: Block | null;
+    at: number;
+}
+/**
+ * A structural board change the per-instance event can't express (a module
+ * materialised, a run cancelled). The client responds with a full refresh.
+ */
+ | {
+    type: 'board';
+    reason: string;
+    at: number;
+}
+/**
+ * A repo-bootstrap run advanced. Carries the updated job (with live `subtasks`)
+ * and its provisional/linked service frame, so the client patches the board
+ * card and its progress without a refetch. `block` is null only if the frame
+ * vanished between the transition and the publish.
+ */
+ | {
+    type: 'bootstrap';
+    job: BootstrapJob;
+    block: Block | null;
+    at: number;
+}
+/**
+ * A human-actionable notification was raised or resolved (a PR needs review, a
+ * pipeline finished and wants confirmation, CI fixing gave up). The client
+ * upserts it into its notifications store and surfaces/clears the board badge.
+ */
+ | {
+    type: 'notification';
+    notification: Notification;
+    at: number;
+}
+/**
+ * One container-agent LLM call completed at the proxy. Carries a COMPACT per-call
+ * summary (no prompt/response bodies) so an open "Model activity" panel updates
+ * live and an evicted-but-alive durable driver is visibly distinct from a wedged
+ * agent — the proxy records calls independently of the execution driver, so these
+ * keep arriving even while the run's poll loop is frozen. The drill-down lazy-loads
+ * the full bodies for an expanded row from the persisted metrics endpoint.
+ */
+ | {
+    type: 'llmCall';
+    call: LlmCallActivity;
+    at: number;
+}
+/**
+ * A block's requirements review changed status (the async incorporate +
+ * re-review cycle started, produced new findings, converged, or hit its cap).
+ * Carries the updated review so an open review window / inspector reflects the
+ * transition live without a refetch. The user is summoned back only via a
+ * `notification` event when input is needed; this event is for live state, not
+ * a summons.
+ */
+ | {
+    type: 'requirements';
+    review: RequirementReview;
+    at: number;
+}
+/**
+ * A consensus session advanced (a participant contributed, a round completed,
+ * the synthesis landed, or it failed). Carries the updated session transcript
+ * so an open Consensus Session window reflects the multi-model process live
+ * without a refetch.
+ */
+ | {
+    type: 'consensus';
+    session: ConsensusSession;
+    at: number;
+}
+/**
+ * A block's clarity (bug-report triage) review changed status — the clarity mirror of
+ * the `requirements` event. Carries the updated review so an open review window /
+ * inspector reflects the transition live without a refetch.
+ */
+ | {
+    type: 'clarity';
+    review: ClarityReview;
+    at: number;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAOjD,MAAM,MAAM,cAAc;AACxB;;;;GAIG;AACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AACrF;;;GAGG;GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AAC/C;;;;;GAKG;GACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AAC3E;;;;GAIG;GACD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,YAAY,EAAE,YAAY,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AAClE;;;;;;;GAOG;GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AACxD;;;;;;;GAOG;GACD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AACjE;;;;;GAKG;GACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AAC9D;;;;GAIG;GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAA"}

package/dist/events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":""}

package/dist/fragment-library.d.ts

@@ -0,0 +1,123 @@
+import * as v from 'valibot';
+/** Which scope owns a managed fragment / source: an account, or a workspace. */
+export declare const fragmentOwnerKindSchema: v.PicklistSchema<["account", "workspace"], undefined>;
+export type FragmentOwnerKind = v.InferOutput<typeof fragmentOwnerKindSchema>;
+/** The three tiers a resolved fragment can originate from, lowest-precedence first. */
+export declare const fragmentTierSchema: v.PicklistSchema<["builtin", "account", "workspace"], undefined>;
+export type FragmentTier = v.InferOutput<typeof fragmentTierSchema>;
+/** Create a hand-authored fragment at a tier. `id` defaults to a slug of the title. */
+export declare const createPromptFragmentSchema: v.ObjectSchema<{
+    readonly id: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
+    readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+    readonly category: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 100, undefined>]>, undefined>;
+    readonly summary: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+    readonly body: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 20000, undefined>]>;
+    readonly tags: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 40, undefined>]>, undefined>, undefined>;
+    readonly appliesTo: v.OptionalSchema<v.ObjectSchema<{
+        readonly blockTypes: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["frontend", "service", "api", "database", "queue", "integration", "external", "environment"], undefined>, undefined>, undefined>;
+        readonly agentKinds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** Semver of the body; defaults to `1.0.0`. */
+    readonly version: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 40, undefined>]>, undefined>;
+}, undefined>;
+export type CreatePromptFragmentInput = v.InferOutput<typeof createPromptFragmentSchema>;
+/** Edit a fragment's body/metadata. Every field is optional (a partial patch). */
+export declare const updatePromptFragmentSchema: v.ObjectSchema<{
+    readonly title: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
+    readonly category: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 100, undefined>]>, undefined>;
+    readonly summary: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    readonly body: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 20000, undefined>]>, undefined>;
+    readonly tags: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 40, undefined>]>, undefined>, undefined>;
+    readonly appliesTo: v.OptionalSchema<v.ObjectSchema<{
+        readonly blockTypes: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["frontend", "service", "api", "database", "queue", "integration", "external", "environment"], undefined>, undefined>, undefined>;
+        readonly agentKinds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly version: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 40, undefined>]>, undefined>;
+}, undefined>;
+export type UpdatePromptFragmentInput = v.InferOutput<typeof updatePromptFragmentSchema>;
+/** A repo a tier links as a source of Markdown guideline files. */
+export declare const fragmentSourceSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly ownerKind: v.PicklistSchema<["account", "workspace"], undefined>;
+    readonly ownerId: v.StringSchema<undefined>;
+    readonly repoOwner: v.StringSchema<undefined>;
+    readonly repoName: v.StringSchema<undefined>;
+    readonly gitRef: v.StringSchema<undefined>;
+    readonly dirPath: v.StringSchema<undefined>;
+    /** Digest of the source tree at the last successful sync; null if never synced. */
+    readonly lastSyncedSha: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly lastSyncedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    readonly createdAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type FragmentSource = v.InferOutput<typeof fragmentSourceSchema>;
+/** Link a repo directory as a fragment source. */
+export declare const linkFragmentSourceSchema: v.ObjectSchema<{
+    readonly repoOwner: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 100, undefined>]>;
+    readonly repoName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+    /** Git ref to read; defaults to the repo's default branch (`HEAD`). */
+    readonly gitRef: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
+    /** Subtree to read (e.g. `guidelines`); defaults to the repo root. */
+    readonly dirPath: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 300, undefined>]>, undefined>;
+}, undefined>;
+export type LinkFragmentSourceInput = v.InferOutput<typeof linkFragmentSourceSchema>;
+/** Outcome of resyncing a source: counts of changed/removed/unchanged files. */
+export declare const fragmentSyncResultSchema: v.ObjectSchema<{
+    readonly upserted: v.NumberSchema<undefined>;
+    readonly tombstoned: v.NumberSchema<undefined>;
+    readonly unchanged: v.NumberSchema<undefined>;
+    readonly lastSyncedSha: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type FragmentSyncResult = v.InferOutput<typeof fragmentSyncResultSchema>;
+/** Cheap "check for changes" result (no writes); powers the resync badge. */
+export declare const fragmentSourceStatusSchema: v.ObjectSchema<{
+    readonly changed: v.BooleanSchema<undefined>;
+    readonly changedCount: v.NumberSchema<undefined>;
+    readonly lastSyncedSha: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly remoteSha: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type FragmentSourceStatus = v.InferOutput<typeof fragmentSourceStatusSchema>;
+/** A fragment as seen after the three tiers are merged for a workspace. */
+export declare const resolvedFragmentSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly version: v.StringSchema<undefined>;
+    readonly title: v.StringSchema<undefined>;
+    readonly category: v.StringSchema<undefined>;
+    readonly summary: v.StringSchema<undefined>;
+    readonly body: v.StringSchema<undefined>;
+    readonly appliesTo: v.OptionalSchema<v.ObjectSchema<{
+        readonly blockTypes: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["frontend", "service", "api", "database", "queue", "integration", "external", "environment"], undefined>, undefined>, undefined>;
+        readonly agentKinds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly tags: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly source: v.OptionalSchema<v.ObjectSchema<{
+        readonly sourceId: v.StringSchema<undefined>;
+        readonly path: v.StringSchema<undefined>;
+        readonly sha: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+    /** Which tier this resolved entry came from after override-by-id. */
+    readonly tier: v.PicklistSchema<["builtin", "account", "workspace"], undefined>;
+}, undefined>;
+export type ResolvedFragment = v.InferOutput<typeof resolvedFragmentSchema>;
+/** The merged catalog as served by `GET /workspaces/:id/prompt-fragments/resolved`. */
+export declare const resolvedFragmentCatalogSchema: v.ArraySchema<v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly version: v.StringSchema<undefined>;
+    readonly title: v.StringSchema<undefined>;
+    readonly category: v.StringSchema<undefined>;
+    readonly summary: v.StringSchema<undefined>;
+    readonly body: v.StringSchema<undefined>;
+    readonly appliesTo: v.OptionalSchema<v.ObjectSchema<{
+        readonly blockTypes: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["frontend", "service", "api", "database", "queue", "integration", "external", "environment"], undefined>, undefined>, undefined>;
+        readonly agentKinds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly tags: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly source: v.OptionalSchema<v.ObjectSchema<{
+        readonly sourceId: v.StringSchema<undefined>;
+        readonly path: v.StringSchema<undefined>;
+        readonly sha: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+    /** Which tier this resolved entry came from after override-by-id. */
+    readonly tier: v.PicklistSchema<["builtin", "account", "workspace"], undefined>;
+}, undefined>, undefined>;
+export type ResolvedFragmentCatalog = v.InferOutput<typeof resolvedFragmentCatalogSchema>;
+//# sourceMappingURL=fragment-library.d.ts.map

package/dist/fragment-library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragment-library.d.ts","sourceRoot":"","sources":["../src/fragment-library.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAa5B,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,uDAAuC,CAAA;AAC3E,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,kEAAkD,CAAA;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AASnE,uFAAuF;AACvF,eAAO,MAAM,0BAA0B;;;;;;;;;;;IAQrC,+CAA+C;;aAE/C,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAExF,kFAAkF;AAClF,eAAO,MAAM,0BAA0B;;;;;;;;;;;aAQrC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAExF,mEAAmE;AACnE,eAAO,MAAM,oBAAoB;;;;;;;;IAQ/B,mFAAmF;;;;aAInF,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,kDAAkD;AAClD,eAAO,MAAM,wBAAwB;;;IAGnC,uEAAuE;;IAEvE,sEAAsE;;aAEtE,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEpF,gFAAgF;AAChF,eAAO,MAAM,wBAAwB;;;;;aAKnC,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E,6EAA6E;AAC7E,eAAO,MAAM,0BAA0B;;;;;aAKrC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF,2EAA2E;AAC3E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;IAEjC,qEAAqE;;aAErE,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,uFAAuF;AACvF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;IANxC,qEAAqE;;yBAMK,CAAA;AAC5E,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA"}

package/dist/fragment-library.js

@@ -0,0 +1,88 @@
+import * as v from 'valibot';
+import { agentKindSchema, blockTypeSchema } from './primitives.js';
+import { promptFragmentSchema } from './entities.js';
+// ---------------------------------------------------------------------------
+// Wire contracts for the tenant-scoped prompt-fragment library (ADR 0006). A
+// resolved catalog for a workspace is the merge of three tiers — built-in,
+// account, workspace — later tiers overriding earlier ones by stable id. Teams
+// curate fragments by hand or link a repo of Markdown guidelines; the catalog is
+// then selected from per run. These shapes back the management UI and the
+// resolved read the run path uses.
+// ---------------------------------------------------------------------------
+/** Which scope owns a managed fragment / source: an account, or a workspace. */
+export const fragmentOwnerKindSchema = v.picklist(['account', 'workspace']);
+/** The three tiers a resolved fragment can originate from, lowest-precedence first. */
+export const fragmentTierSchema = v.picklist(['builtin', 'account', 'workspace']);
+const appliesToSchema = v.object({
+    blockTypes: v.optional(v.array(blockTypeSchema)),
+    agentKinds: v.optional(v.array(agentKindSchema)),
+});
+const tagsSchema = v.array(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(40)));
+/** Create a hand-authored fragment at a tier. `id` defaults to a slug of the title. */
+export const createPromptFragmentSchema = v.object({
+    id: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200))),
+    title: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200)),
+    category: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(100))),
+    summary: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(500)),
+    body: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(20000)),
+    tags: v.optional(tagsSchema),
+    appliesTo: v.optional(appliesToSchema),
+    /** Semver of the body; defaults to `1.0.0`. */
+    version: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(40))),
+});
+/** Edit a fragment's body/metadata. Every field is optional (a partial patch). */
+export const updatePromptFragmentSchema = v.object({
+    title: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200))),
+    category: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(100))),
+    summary: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(500))),
+    body: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(20000))),
+    tags: v.optional(tagsSchema),
+    appliesTo: v.optional(appliesToSchema),
+    version: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(40))),
+});
+/** A repo a tier links as a source of Markdown guideline files. */
+export const fragmentSourceSchema = v.object({
+    id: v.string(),
+    ownerKind: fragmentOwnerKindSchema,
+    ownerId: v.string(),
+    repoOwner: v.string(),
+    repoName: v.string(),
+    gitRef: v.string(),
+    dirPath: v.string(),
+    /** Digest of the source tree at the last successful sync; null if never synced. */
+    lastSyncedSha: v.nullable(v.string()),
+    lastSyncedAt: v.nullable(v.number()),
+    createdAt: v.number(),
+});
+/** Link a repo directory as a fragment source. */
+export const linkFragmentSourceSchema = v.object({
+    repoOwner: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(100)),
+    repoName: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200)),
+    /** Git ref to read; defaults to the repo's default branch (`HEAD`). */
+    gitRef: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200))),
+    /** Subtree to read (e.g. `guidelines`); defaults to the repo root. */
+    dirPath: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(300))),
+});
+/** Outcome of resyncing a source: counts of changed/removed/unchanged files. */
+export const fragmentSyncResultSchema = v.object({
+    upserted: v.number(),
+    tombstoned: v.number(),
+    unchanged: v.number(),
+    lastSyncedSha: v.nullable(v.string()),
+});
+/** Cheap "check for changes" result (no writes); powers the resync badge. */
+export const fragmentSourceStatusSchema = v.object({
+    changed: v.boolean(),
+    changedCount: v.number(),
+    lastSyncedSha: v.nullable(v.string()),
+    remoteSha: v.nullable(v.string()),
+});
+/** A fragment as seen after the three tiers are merged for a workspace. */
+export const resolvedFragmentSchema = v.object({
+    ...promptFragmentSchema.entries,
+    /** Which tier this resolved entry came from after override-by-id. */
+    tier: fragmentTierSchema,
+});
+/** The merged catalog as served by `GET /workspaces/:id/prompt-fragments/resolved`. */
+export const resolvedFragmentCatalogSchema = v.array(resolvedFragmentSchema);
+//# sourceMappingURL=fragment-library.js.map

package/dist/fragment-library.js.map

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