@sylphx/contract 0.2.0

package/dist/schemas/admin-bootstrap.js

@@ -0,0 +1,37 @@
+/**
+ * Admin Bootstrap — reset-bootstrap-window schema (ADR-089 §2.7 Phase 7 Commit B).
+ *
+ * Platform-plane endpoint that forcibly re-opens the Appwrite-pattern
+ * bootstrap window for an already-booted cluster. The window normally
+ * opens ONCE at first boot (SETNX with 10-min TTL) and closes itself on
+ * first successful super-admin signup. This reset path is the documented
+ * recovery for:
+ *
+ *   - Operator missed the window (10 minutes elapsed without signup).
+ *   - A second recovery super-admin needs to be created later (e.g. the
+ *     original admin's credentials are lost and there are no other
+ *     admins to promote via the admin-users surface).
+ *
+ * Auth: `superAdminAuth` (platform session cookie, super_admin role) —
+ * see `apps/api/src/server/platform/middleware/auth.ts:462`. Deliberately
+ * NOT service-token-scoped: this is a power operator action, not an
+ * automation hook; it SHOULD require a human-in-the-loop session.
+ */
+import { Schema } from 'effect';
+/** Input: no body. The POST verb + super-admin auth is the whole request. */
+export const ResetBootstrapWindowInput = Schema.Struct({}).annotations({
+    identifier: 'ResetBootstrapWindowInput',
+    description: 'Empty body — the authenticated POST is itself the signal.',
+});
+/** Output: confirm window state + TTL so the caller knows when it expires. */
+export const ResetBootstrapWindowResult = Schema.Struct({
+    /** Always `true` when the endpoint returns 200. */
+    opened: Schema.Boolean,
+    /** Seconds until the window closes again. Mirrors `BOOTSTRAP_WINDOW_TTL_SECONDS`. */
+    ttlSeconds: Schema.Number,
+    /** Human-readable instruction for the next step. */
+    message: Schema.String,
+}).annotations({
+    identifier: 'ResetBootstrapWindowResult',
+    description: 'Bootstrap window reset confirmation (ADR-089 §2.7).',
+});

package/dist/schemas/admin-broadcasts.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Admin Broadcasts — internal operator console schemas for broadcast management.
+ * Mirrors `/admin/broadcasts/*` in `apps/api/src/server/platform/routes/admin/broadcasts.ts`.
+ *
+ * Plane: `admin`.
+ */
+import { Schema } from 'effect';
+export declare const AdminBroadcastType: Schema.Literal<["email", "push", "in_app"]>;
+export type AdminBroadcastType = typeof AdminBroadcastType.Type;
+export declare const AdminBroadcastStatus: Schema.Literal<["draft", "scheduled", "sending", "sent", "failed"]>;
+export type AdminBroadcastStatus = typeof AdminBroadcastStatus.Type;
+export declare const AdminTargetSegment: Schema.Literal<["all", "active", "premium"]>;
+export type AdminTargetSegment = typeof AdminTargetSegment.Type;
+export declare const AdminBroadcastStats: Schema.Struct<{
+    totalRecipients: Schema.optional<typeof Schema.Number>;
+    sent: Schema.optional<typeof Schema.Number>;
+    opened: Schema.optional<typeof Schema.Number>;
+    clicked: Schema.optional<typeof Schema.Number>;
+    bounced: Schema.optional<typeof Schema.Number>;
+    unsubscribed: Schema.optional<typeof Schema.Number>;
+}>;
+export type AdminBroadcastStats = typeof AdminBroadcastStats.Type;
+export declare const AdminBroadcastCreator: Schema.Struct<{
+    id: typeof Schema.String;
+    name: Schema.NullOr<typeof Schema.String>;
+    email: typeof Schema.String;
+}>;
+export type AdminBroadcastCreator = typeof AdminBroadcastCreator.Type;
+export declare const AdminBroadcastListItem: Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["email", "push", "in_app"]>;
+    status: Schema.Literal<["draft", "scheduled", "sending", "sent", "failed"]>;
+    targetSegment: typeof Schema.String;
+    subject: Schema.NullOr<typeof Schema.String>;
+    scheduledAt: Schema.NullOr<typeof Schema.String>;
+    sentAt: Schema.NullOr<typeof Schema.String>;
+    stats: Schema.NullOr<Schema.Struct<{
+        totalRecipients: Schema.optional<typeof Schema.Number>;
+        sent: Schema.optional<typeof Schema.Number>;
+        opened: Schema.optional<typeof Schema.Number>;
+        clicked: Schema.optional<typeof Schema.Number>;
+        bounced: Schema.optional<typeof Schema.Number>;
+        unsubscribed: Schema.optional<typeof Schema.Number>;
+    }>>;
+    createdAt: typeof Schema.String;
+    createdBy: Schema.NullOr<Schema.Struct<{
+        id: typeof Schema.String;
+        name: Schema.NullOr<typeof Schema.String>;
+        email: typeof Schema.String;
+    }>>;
+}>;
+export type AdminBroadcastListItem = typeof AdminBroadcastListItem.Type;
+export declare const AdminBroadcast: Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["email", "push", "in_app"]>;
+    status: Schema.Literal<["draft", "scheduled", "sending", "sent", "failed"]>;
+    targetSegment: typeof Schema.String;
+    targetAppIds: Schema.NullOr<Schema.Array$<typeof Schema.String>>;
+    subject: Schema.NullOr<typeof Schema.String>;
+    content: Schema.NullOr<typeof Schema.String>;
+    richContent: Schema.NullOr<typeof Schema.Unknown>;
+    scheduledAt: Schema.NullOr<typeof Schema.String>;
+    sentAt: Schema.NullOr<typeof Schema.String>;
+    stats: Schema.NullOr<Schema.Struct<{
+        totalRecipients: Schema.optional<typeof Schema.Number>;
+        sent: Schema.optional<typeof Schema.Number>;
+        opened: Schema.optional<typeof Schema.Number>;
+        clicked: Schema.optional<typeof Schema.Number>;
+        bounced: Schema.optional<typeof Schema.Number>;
+        unsubscribed: Schema.optional<typeof Schema.Number>;
+    }>>;
+    createdBy: Schema.NullOr<typeof Schema.String>;
+    createdAt: typeof Schema.String;
+    updatedAt: typeof Schema.String;
+}>;
+export type AdminBroadcast = typeof AdminBroadcast.Type;
+export declare const AdminBroadcastIdParams: Schema.Struct<{
+    id: typeof Schema.String;
+}>;
+export type AdminBroadcastIdParams = typeof AdminBroadcastIdParams.Type;
+export declare const AdminBroadcastProjectQuery: Schema.Struct<{
+    projectId: typeof Schema.String;
+}>;
+export type AdminBroadcastProjectQuery = typeof AdminBroadcastProjectQuery.Type;
+export declare const AdminListBroadcastsQuery: Schema.Struct<{
+    projectId: typeof Schema.String;
+    limit: Schema.optional<typeof Schema.String>;
+    offset: Schema.optional<typeof Schema.String>;
+}>;
+export type AdminListBroadcastsQuery = typeof AdminListBroadcastsQuery.Type;
+export declare const AdminCreateBroadcastInput: Schema.Struct<{
+    type: Schema.Literal<["email", "push", "in_app"]>;
+    targetSegment: Schema.optional<Schema.Literal<["all", "active", "premium"]>>;
+    targetAppIds: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    subject: Schema.optional<typeof Schema.String>;
+    content: typeof Schema.String;
+    scheduledAt: Schema.optional<typeof Schema.String>;
+}>;
+export type AdminCreateBroadcastInput = typeof AdminCreateBroadcastInput.Type;
+export declare const AdminCreateBroadcastResult: Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["email", "push", "in_app"]>;
+    status: Schema.Literal<["draft", "scheduled", "sending", "sent", "failed"]>;
+    subject: Schema.NullOr<typeof Schema.String>;
+    scheduledAt: Schema.NullOr<typeof Schema.String>;
+    createdAt: typeof Schema.String;
+}>;
+export type AdminCreateBroadcastResult = typeof AdminCreateBroadcastResult.Type;
+export declare const AdminListBroadcastsResult: Schema.Struct<{
+    broadcasts: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        type: Schema.Literal<["email", "push", "in_app"]>;
+        status: Schema.Literal<["draft", "scheduled", "sending", "sent", "failed"]>;
+        targetSegment: typeof Schema.String;
+        subject: Schema.NullOr<typeof Schema.String>;
+        scheduledAt: Schema.NullOr<typeof Schema.String>;
+        sentAt: Schema.NullOr<typeof Schema.String>;
+        stats: Schema.NullOr<Schema.Struct<{
+            totalRecipients: Schema.optional<typeof Schema.Number>;
+            sent: Schema.optional<typeof Schema.Number>;
+            opened: Schema.optional<typeof Schema.Number>;
+            clicked: Schema.optional<typeof Schema.Number>;
+            bounced: Schema.optional<typeof Schema.Number>;
+            unsubscribed: Schema.optional<typeof Schema.Number>;
+        }>>;
+        createdAt: typeof Schema.String;
+        createdBy: Schema.NullOr<Schema.Struct<{
+            id: typeof Schema.String;
+            name: Schema.NullOr<typeof Schema.String>;
+            email: typeof Schema.String;
+        }>>;
+    }>>;
+    total: typeof Schema.Number;
+}>;
+export type AdminListBroadcastsResult = typeof AdminListBroadcastsResult.Type;
+export declare const AdminGetBroadcastResult: Schema.Struct<{
+    broadcast: Schema.Struct<{
+        id: typeof Schema.String;
+        type: Schema.Literal<["email", "push", "in_app"]>;
+        status: Schema.Literal<["draft", "scheduled", "sending", "sent", "failed"]>;
+        targetSegment: typeof Schema.String;
+        targetAppIds: Schema.NullOr<Schema.Array$<typeof Schema.String>>;
+        subject: Schema.NullOr<typeof Schema.String>;
+        content: Schema.NullOr<typeof Schema.String>;
+        richContent: Schema.NullOr<typeof Schema.Unknown>;
+        scheduledAt: Schema.NullOr<typeof Schema.String>;
+        sentAt: Schema.NullOr<typeof Schema.String>;
+        stats: Schema.NullOr<Schema.Struct<{
+            totalRecipients: Schema.optional<typeof Schema.Number>;
+            sent: Schema.optional<typeof Schema.Number>;
+            opened: Schema.optional<typeof Schema.Number>;
+            clicked: Schema.optional<typeof Schema.Number>;
+            bounced: Schema.optional<typeof Schema.Number>;
+            unsubscribed: Schema.optional<typeof Schema.Number>;
+        }>>;
+        createdBy: Schema.NullOr<typeof Schema.String>;
+        createdAt: typeof Schema.String;
+        updatedAt: typeof Schema.String;
+    }>;
+}>;
+export type AdminGetBroadcastResult = typeof AdminGetBroadcastResult.Type;
+export declare const AdminSendBroadcastStats: Schema.Struct<{
+    totalRecipients: typeof Schema.Number;
+    sent: typeof Schema.Number;
+    failed: typeof Schema.Number;
+}>;
+export type AdminSendBroadcastStats = typeof AdminSendBroadcastStats.Type;
+export declare const AdminSendBroadcastResult: Schema.Struct<{
+    success: typeof Schema.Boolean;
+    stats: Schema.Struct<{
+        totalRecipients: typeof Schema.Number;
+        sent: typeof Schema.Number;
+        failed: typeof Schema.Number;
+    }>;
+}>;
+export type AdminSendBroadcastResult = typeof AdminSendBroadcastResult.Type;
+export declare const AdminDeleteBroadcastResult: Schema.Struct<{
+    success: typeof Schema.Boolean;
+}>;
+export type AdminDeleteBroadcastResult = typeof AdminDeleteBroadcastResult.Type;
+//# sourceMappingURL=admin-broadcasts.d.ts.map

package/dist/schemas/admin-broadcasts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-broadcasts.d.ts","sourceRoot":"","sources":["../../src/schemas/admin-broadcasts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,eAAO,MAAM,kBAAkB,6CAA4C,CAAA;AAC3E,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D,eAAO,MAAM,oBAAoB,qEAMhC,CAAA;AACD,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE,eAAO,MAAM,kBAAkB,8CAA6C,CAAA;AAC5E,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D,eAAO,MAAM,mBAAmB;;;;;;;EAO9B,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;AAEjE,eAAO,MAAM,qBAAqB;;;;EAIhC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA;AAErE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;EAWjC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;AAEvE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;EAezB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAIvD,eAAO,MAAM,sBAAsB;;EAAuC,CAAA;AAC1E,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;AAIvE,eAAO,MAAM,0BAA0B;;EAA8C,CAAA;AACrF,MAAM,MAAM,0BAA0B,GAAG,OAAO,0BAA0B,CAAC,IAAI,CAAA;AAE/E,eAAO,MAAM,wBAAwB;;;;EAInC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,OAAO,wBAAwB,CAAC,IAAI,CAAA;AAI3E,eAAO,MAAM,yBAAyB;;;;;;;EAOpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAI7E,eAAO,MAAM,0BAA0B;;;;;;;EAOrC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,OAAO,0BAA0B,CAAC,IAAI,CAAA;AAE/E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;EAGpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAE7E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;EAA+C,CAAA;AACnF,MAAM,MAAM,uBAAuB,GAAG,OAAO,uBAAuB,CAAC,IAAI,CAAA;AAEzE,eAAO,MAAM,uBAAuB;;;;EAIlC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,OAAO,uBAAuB,CAAC,IAAI,CAAA;AAEzE,eAAO,MAAM,wBAAwB;;;;;;;EAGnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,OAAO,wBAAwB,CAAC,IAAI,CAAA;AAE3E,eAAO,MAAM,0BAA0B;;EAA6C,CAAA;AACpF,MAAM,MAAM,0BAA0B,GAAG,OAAO,0BAA0B,CAAC,IAAI,CAAA"}

package/dist/schemas/admin-broadcasts.js

@@ -0,0 +1,93 @@
+/**
+ * Admin Broadcasts — internal operator console schemas for broadcast management.
+ * Mirrors `/admin/broadcasts/*` in `apps/api/src/server/platform/routes/admin/broadcasts.ts`.
+ *
+ * Plane: `admin`.
+ */
+import { Schema } from 'effect';
+export const AdminBroadcastType = Schema.Literal('email', 'push', 'in_app');
+export const AdminBroadcastStatus = Schema.Literal('draft', 'scheduled', 'sending', 'sent', 'failed');
+export const AdminTargetSegment = Schema.Literal('all', 'active', 'premium');
+export const AdminBroadcastStats = Schema.Struct({
+    totalRecipients: Schema.optional(Schema.Number),
+    sent: Schema.optional(Schema.Number),
+    opened: Schema.optional(Schema.Number),
+    clicked: Schema.optional(Schema.Number),
+    bounced: Schema.optional(Schema.Number),
+    unsubscribed: Schema.optional(Schema.Number),
+});
+export const AdminBroadcastCreator = Schema.Struct({
+    id: Schema.String,
+    name: Schema.NullOr(Schema.String),
+    email: Schema.String,
+});
+export const AdminBroadcastListItem = Schema.Struct({
+    id: Schema.String,
+    type: AdminBroadcastType,
+    status: AdminBroadcastStatus,
+    targetSegment: Schema.String,
+    subject: Schema.NullOr(Schema.String),
+    scheduledAt: Schema.NullOr(Schema.String),
+    sentAt: Schema.NullOr(Schema.String),
+    stats: Schema.NullOr(AdminBroadcastStats),
+    createdAt: Schema.String,
+    createdBy: Schema.NullOr(AdminBroadcastCreator),
+});
+export const AdminBroadcast = Schema.Struct({
+    id: Schema.String,
+    type: AdminBroadcastType,
+    status: AdminBroadcastStatus,
+    targetSegment: Schema.String,
+    targetAppIds: Schema.NullOr(Schema.Array(Schema.String)),
+    subject: Schema.NullOr(Schema.String),
+    content: Schema.NullOr(Schema.String),
+    richContent: Schema.NullOr(Schema.Unknown),
+    scheduledAt: Schema.NullOr(Schema.String),
+    sentAt: Schema.NullOr(Schema.String),
+    stats: Schema.NullOr(AdminBroadcastStats),
+    createdBy: Schema.NullOr(Schema.String),
+    createdAt: Schema.String,
+    updatedAt: Schema.String,
+});
+// ── Params ─────────────────────────────────────────────────────────────────
+export const AdminBroadcastIdParams = Schema.Struct({ id: Schema.String });
+// ── Query ──────────────────────────────────────────────────────────────────
+export const AdminBroadcastProjectQuery = Schema.Struct({ projectId: Schema.String });
+export const AdminListBroadcastsQuery = Schema.Struct({
+    projectId: Schema.String,
+    limit: Schema.optional(Schema.String),
+    offset: Schema.optional(Schema.String),
+});
+// ── Inputs ─────────────────────────────────────────────────────────────────
+export const AdminCreateBroadcastInput = Schema.Struct({
+    type: AdminBroadcastType,
+    targetSegment: Schema.optional(AdminTargetSegment),
+    targetAppIds: Schema.optional(Schema.Array(Schema.String)),
+    subject: Schema.optional(Schema.String),
+    content: Schema.String,
+    scheduledAt: Schema.optional(Schema.String),
+});
+// ── Responses ──────────────────────────────────────────────────────────────
+export const AdminCreateBroadcastResult = Schema.Struct({
+    id: Schema.String,
+    type: AdminBroadcastType,
+    status: AdminBroadcastStatus,
+    subject: Schema.NullOr(Schema.String),
+    scheduledAt: Schema.NullOr(Schema.String),
+    createdAt: Schema.String,
+});
+export const AdminListBroadcastsResult = Schema.Struct({
+    broadcasts: Schema.Array(AdminBroadcastListItem),
+    total: Schema.Number,
+});
+export const AdminGetBroadcastResult = Schema.Struct({ broadcast: AdminBroadcast });
+export const AdminSendBroadcastStats = Schema.Struct({
+    totalRecipients: Schema.Number,
+    sent: Schema.Number,
+    failed: Schema.Number,
+});
+export const AdminSendBroadcastResult = Schema.Struct({
+    success: Schema.Boolean,
+    stats: AdminSendBroadcastStats,
+});
+export const AdminDeleteBroadcastResult = Schema.Struct({ success: Schema.Boolean });

package/dist/schemas/admin-builds.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Admin Builds — recovery-operation schemas (OPS-1 + OPS-7).
+ *
+ * Mirrors `apps/api/src/server/platform/routes/admin/builds.ts`. Replaces
+ * the manual `UPDATE build_records SET status='failed' …` from the
+ * `BuildRecordsStuckInBuilding` runbook (line 117–127, 141–147) with a
+ * structured admin endpoint. Operators reach this endpoint via the CLI
+ * (`sylphx admin builds reap`) — no future agent should need to enter the
+ * DB shell to clear a stuck build queue.
+ *
+ * Plane: `admin` (super-admin / scoped service-token only — scope
+ * `platform:builds:reap`).
+ *
+ * OPS-7 fold-in: an optional `imageDigest` filter clears builds whose
+ * stale image-digest reference is also blocking GC outreach. Same audit
+ * row, same scope, same writer.
+ */
+import { Schema } from 'effect';
+/**
+ * Body of `POST /admin/builds/reap`.
+ *
+ * Semantics:
+ *
+ *   - `olderThan` — required. Any `build_records` row whose `status='building'`
+ *     AND whose `started_at < NOW() - <olderThan>` is in the candidate set.
+ *     Rows whose `started_at IS NULL` are NOT touched: a NULL `started_at`
+ *     means the K8s Job never transitioned to Active, which is a different
+ *     failure mode (queue starvation) handled by a separate runbook.
+ *   - `dryRun` — when true, the endpoint returns the candidate set without
+ *     mutating anything. `reason` becomes optional in this mode.
+ *   - `reason` — written to `audit_logs.metadata.reason`. Required unless
+ *     `dryRun=true`. The endpoint rejects with 400 when missing in a
+ *     non-dry-run call.
+ *   - `imageDigest` — optional OPS-7 fold-in. When present, the reaper
+ *     restricts the candidate set to rows where `image_digest = <digest>`
+ *     AND clears `image_digest` on each reaped row (preserves the audit
+ *     trail by leaving `failure_reason` / `finished_at` populated).
+ *
+ * Resulting UPDATE on a non-dry-run call (single statement, no app-side
+ * loop):
+ *
+ *   UPDATE build_records
+ *      SET status         = 'failed',
+ *          finished_at    = NOW(),
+ *          failure_reason = 'admin reap: ' || $reason
+ *        [, image_digest  = NULL]              -- only if imageDigest passed
+ *    WHERE status = 'building'
+ *      AND started_at IS NOT NULL
+ *      AND started_at < NOW() - $olderThan
+ *      [AND image_digest = $imageDigest]       -- only if imageDigest passed
+ *    RETURNING id, project_id, env_id, started_at;
+ */
+export declare const AdminBuildsReapInput: Schema.Struct<{
+    olderThan: Schema.filter<typeof Schema.String>;
+    dryRun: Schema.optional<typeof Schema.Boolean>;
+    reason: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    imageDigest: Schema.optional<Schema.filter<typeof Schema.String>>;
+}>;
+export type AdminBuildsReapInput = typeof AdminBuildsReapInput.Type;
+/**
+ * One row from the reaper's `RETURNING` clause (or the dry-run candidate
+ * set). Surfaces the minimum the operator needs to triage in the CLI:
+ * which project, which environment, how old.
+ *
+ * `id` and `projectId` are TypeIDs (`bld_xxx`, `proj_xxx`) — never raw
+ * UUIDs. `envId` is a TypeID (`env_xxx`).
+ *
+ * `ageSeconds` is the wall-clock age of the row at reap time
+ * (`extract(epoch from now() - started_at)`), so dashboards can render
+ * "stuck for X hours" without re-deriving from a server-clock-dependent
+ * `startedAt` ISO string.
+ */
+export declare const AdminBuildsReapRecord: Schema.Struct<{
+    id: typeof Schema.String;
+    projectId: typeof Schema.String;
+    envId: typeof Schema.String;
+    startedAt: typeof Schema.String;
+    ageSeconds: typeof Schema.Number;
+}>;
+export type AdminBuildsReapRecord = typeof AdminBuildsReapRecord.Type;
+/**
+ * Result envelope.
+ *
+ *   - `dryRun`  — echo of the input flag. Lets the caller assert
+ *                 invariants without re-parsing their own request.
+ *   - `reaped`  — number of rows transitioned (0 on dry-run).
+ *   - `records` — full list of rows in the candidate set (dry-run) or
+ *                 the rows actually flipped (write path). Capped at 1000
+ *                 — at higher volumes the operator should narrow
+ *                 `olderThan` instead of relying on a single mega-reap.
+ *   - `digestCleared` — number of rows whose stale `image_digest` was
+ *                       additionally nulled (always 0 unless OPS-7 fold-in
+ *                       was triggered with `imageDigest`).
+ */
+export declare const AdminBuildsReapResult: Schema.Struct<{
+    dryRun: typeof Schema.Boolean;
+    reaped: typeof Schema.Number;
+    digestCleared: typeof Schema.Number;
+    records: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        projectId: typeof Schema.String;
+        envId: typeof Schema.String;
+        startedAt: typeof Schema.String;
+        ageSeconds: typeof Schema.Number;
+    }>>;
+}>;
+export type AdminBuildsReapResult = typeof AdminBuildsReapResult.Type;
+//# sourceMappingURL=admin-builds.d.ts.map

package/dist/schemas/admin-builds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-builds.d.ts","sourceRoot":"","sources":["../../src/schemas/admin-builds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAsC/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAInE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB;;;;;;EAMhC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA;AAErE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;EAKhC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA"}

package/dist/schemas/admin-builds.js

@@ -0,0 +1,127 @@
+/**
+ * Admin Builds — recovery-operation schemas (OPS-1 + OPS-7).
+ *
+ * Mirrors `apps/api/src/server/platform/routes/admin/builds.ts`. Replaces
+ * the manual `UPDATE build_records SET status='failed' …` from the
+ * `BuildRecordsStuckInBuilding` runbook (line 117–127, 141–147) with a
+ * structured admin endpoint. Operators reach this endpoint via the CLI
+ * (`sylphx admin builds reap`) — no future agent should need to enter the
+ * DB shell to clear a stuck build queue.
+ *
+ * Plane: `admin` (super-admin / scoped service-token only — scope
+ * `platform:builds:reap`).
+ *
+ * OPS-7 fold-in: an optional `imageDigest` filter clears builds whose
+ * stale image-digest reference is also blocking GC outreach. Same audit
+ * row, same scope, same writer.
+ */
+import { Schema } from 'effect';
+// ─── Input ──────────────────────────────────────────────────────────────
+/**
+ * Duration string accepted by the reap endpoint. Subset of Go's `time.ParseDuration`
+ * grammar that the API actually consumes:
+ *
+ *   ^[0-9]+(s|m|h|d)$    — `30m`, `2h`, `1d`, `7200s`
+ *
+ * Anything else 400s. Keeping the grammar narrow lets ops scripts compose
+ * the value safely without accidental injection of negative offsets or
+ * zero-length windows.
+ */
+const Duration = Schema.String.pipe(Schema.pattern(/^[0-9]+(s|m|h|d)$/, {
+    message: () => 'olderThan must match ^[0-9]+(s|m|h|d)$ (e.g. "30m", "2h", "1d")',
+}));
+/**
+ * SHA-256 image digest, when the reaper should ALSO null out the
+ * `image_digest` column on matched rows (OPS-7 fold-in).
+ */
+const ImageDigest = Schema.String.pipe(Schema.pattern(/^sha256:[a-f0-9]{64}$/, {
+    message: () => 'imageDigest must match ^sha256:[a-f0-9]{64}$',
+}));
+/**
+ * Reason string for the audit trail. Required unless `dryRun=true`.
+ *
+ * Length-bounded to keep the audit row size predictable and to nudge
+ * operators toward terse-but-useful narratives.
+ */
+const Reason = Schema.String.pipe(Schema.minLength(3), Schema.maxLength(500));
+/**
+ * Body of `POST /admin/builds/reap`.
+ *
+ * Semantics:
+ *
+ *   - `olderThan` — required. Any `build_records` row whose `status='building'`
+ *     AND whose `started_at < NOW() - <olderThan>` is in the candidate set.
+ *     Rows whose `started_at IS NULL` are NOT touched: a NULL `started_at`
+ *     means the K8s Job never transitioned to Active, which is a different
+ *     failure mode (queue starvation) handled by a separate runbook.
+ *   - `dryRun` — when true, the endpoint returns the candidate set without
+ *     mutating anything. `reason` becomes optional in this mode.
+ *   - `reason` — written to `audit_logs.metadata.reason`. Required unless
+ *     `dryRun=true`. The endpoint rejects with 400 when missing in a
+ *     non-dry-run call.
+ *   - `imageDigest` — optional OPS-7 fold-in. When present, the reaper
+ *     restricts the candidate set to rows where `image_digest = <digest>`
+ *     AND clears `image_digest` on each reaped row (preserves the audit
+ *     trail by leaving `failure_reason` / `finished_at` populated).
+ *
+ * Resulting UPDATE on a non-dry-run call (single statement, no app-side
+ * loop):
+ *
+ *   UPDATE build_records
+ *      SET status         = 'failed',
+ *          finished_at    = NOW(),
+ *          failure_reason = 'admin reap: ' || $reason
+ *        [, image_digest  = NULL]              -- only if imageDigest passed
+ *    WHERE status = 'building'
+ *      AND started_at IS NOT NULL
+ *      AND started_at < NOW() - $olderThan
+ *      [AND image_digest = $imageDigest]       -- only if imageDigest passed
+ *    RETURNING id, project_id, env_id, started_at;
+ */
+export const AdminBuildsReapInput = Schema.Struct({
+    olderThan: Duration,
+    dryRun: Schema.optional(Schema.Boolean),
+    reason: Schema.optional(Reason),
+    imageDigest: Schema.optional(ImageDigest),
+});
+// ─── Output ─────────────────────────────────────────────────────────────
+/**
+ * One row from the reaper's `RETURNING` clause (or the dry-run candidate
+ * set). Surfaces the minimum the operator needs to triage in the CLI:
+ * which project, which environment, how old.
+ *
+ * `id` and `projectId` are TypeIDs (`bld_xxx`, `proj_xxx`) — never raw
+ * UUIDs. `envId` is a TypeID (`env_xxx`).
+ *
+ * `ageSeconds` is the wall-clock age of the row at reap time
+ * (`extract(epoch from now() - started_at)`), so dashboards can render
+ * "stuck for X hours" without re-deriving from a server-clock-dependent
+ * `startedAt` ISO string.
+ */
+export const AdminBuildsReapRecord = Schema.Struct({
+    id: Schema.String,
+    projectId: Schema.String,
+    envId: Schema.String,
+    startedAt: Schema.String,
+    ageSeconds: Schema.Number,
+});
+/**
+ * Result envelope.
+ *
+ *   - `dryRun`  — echo of the input flag. Lets the caller assert
+ *                 invariants without re-parsing their own request.
+ *   - `reaped`  — number of rows transitioned (0 on dry-run).
+ *   - `records` — full list of rows in the candidate set (dry-run) or
+ *                 the rows actually flipped (write path). Capped at 1000
+ *                 — at higher volumes the operator should narrow
+ *                 `olderThan` instead of relying on a single mega-reap.
+ *   - `digestCleared` — number of rows whose stale `image_digest` was
+ *                       additionally nulled (always 0 unless OPS-7 fold-in
+ *                       was triggered with `imageDigest`).
+ */
+export const AdminBuildsReapResult = Schema.Struct({
+    dryRun: Schema.Boolean,
+    reaped: Schema.Number,
+    digestCleared: Schema.Number,
+    records: Schema.Array(AdminBuildsReapRecord),
+});