@forgrit/shared-contracts-jobs-queue 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog — @forgrit/shared-contracts-jobs-queue
+
+## [0.1.0] — 2026-05-26
+
+### Added — initial public release
+
+- `IJobsService` interface (3 methods: createStep, getJob, getFrozenPrompt) + `JOBS_SERVICE` Symbol token
+- `IQueueService` interface (1 method: enqueue) + `QUEUE_SERVICE` Symbol token
+- `IJobStepService` interface (2 methods) + `JOB_STEP_SERVICE` Symbol token
+- `StepType`, `StepStatus`, `JobStatus` enum types (re-exported from @forgrit/contracts)
+- Sub-path exports: `./jobs`, `./queue`
+
+### Notes
+
+- Narrow-surface discipline (FM-A from plan #5.05): 3 of 22 JobsService methods + 1 of 13 QueueService methods + 2 of N JobStepService methods. Consumers depend on the contracts; ForGrit's internal implementations may add private methods without breaking the contract.
+- Designed for the BullMQ singleton-invariant pattern: consumers wire `useExisting: ConcreteJobsService` so DI never creates a duplicate Queue/Worker.
+- Node 20+. Peer dep: `@nestjs/common`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForGrit AI <forgritai@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @forgrit/shared-contracts-jobs-queue
+
+> Type-only contracts + NestJS DI Symbol tokens for ForGrit job + queue services — `IJobsService` (3 methods), `IQueueService` (1 method), `IJobStepService` (2 methods).
+
+[![npm version](https://img.shields.io/npm/v/@forgrit/shared-contracts-jobs-queue.svg)](https://www.npmjs.com/package/@forgrit/shared-contracts-jobs-queue)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+> **Status: early-access (v0.x).** Internal-monorepo seam package. Pre-1.0 may include breaking changes in minor bumps.
+
+Narrow-surface contracts: 3 + 1 + 2 = **6 total method signatures** across the 3 interfaces. ForGrit's internal implementations may have many more methods; the contracts capture only what cross-domain consumers depend on.
+
+---
+
+## Install
+
+```bash
+npm install @forgrit/shared-contracts-jobs-queue
+```
+
+Peer: `@nestjs/common`.
+
+## Sub-modules
+
+```ts
+import { IJobsService, JOBS_SERVICE } from '@forgrit/shared-contracts-jobs-queue/jobs';
+import { IQueueService, QUEUE_SERVICE } from '@forgrit/shared-contracts-jobs-queue/queue';
+```
+
+## Pattern
+
+Use `useExisting` so DI never creates a duplicate BullMQ Queue/Worker:
+
+```ts
+@Module({
+  providers: [MyJobsService, { provide: JOBS_SERVICE, useExisting: MyJobsService }],
+})
+export class MyModule {}
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Sibling packages
+
+- [`@forgrit/shared-contracts-platform`](https://www.npmjs.com/package/@forgrit/shared-contracts-platform) — auth + logger + db contracts
+- [`@forgrit/shared-contracts-prompt`](https://www.npmjs.com/package/@forgrit/shared-contracts-prompt) — prompt-pipeline contracts
+- [`@forgrit/contracts`](https://www.npmjs.com/package/@forgrit/contracts) — domain Zod schemas + types

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * as jobs from './jobs';
+export * as queue from './queue';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,57 @@
+"use strict";
+// @forgrit/shared-contracts-jobs-queue — public surface.
+//
+// Plan #5.05 (2026-05-25) — third contract package, sibling to
+// @forgrit/shared-contracts-platform (plan #4.4) and
+// @forgrit/shared-contracts-design-composition (plans #4.55 + #4.57).
+//
+// Surface:
+//   - Types: IJobsService (3 methods), IQueueService (1 method)
+//   - DI tokens: JOBS_SERVICE, QUEUE_SERVICE (both Symbol.for global)
+//   - No runtime values beyond the 2 Symbol tokens.
+//
+// Sub-path exports are preferred for tree-shaking:
+//   import { IJobsService, JOBS_SERVICE } from '@forgrit/shared-contracts-jobs-queue/jobs';
+//   import { IQueueService, QUEUE_SERVICE } from '@forgrit/shared-contracts-jobs-queue/queue';
+// The root barrel exists for convenience only.
+//
+// No dependency on @forgrit/shared-contracts-platform OR
+// @forgrit/shared-contracts-design-composition — orthogonal surfaces.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queue = exports.jobs = void 0;
+exports.jobs = __importStar(require("./jobs"));
+exports.queue = __importStar(require("./queue"));
+//# sourceMappingURL=index.js.map

package/dist/jobs/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './tokens';
+//# sourceMappingURL=index.d.ts.map

package/dist/jobs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./tokens"), exports);
+//# sourceMappingURL=index.js.map

package/dist/jobs/tokens.d.ts

@@ -0,0 +1,24 @@
+/**
+ * JOBS_SERVICE — Symbol.for() (global registry) DI token for IJobsService.
+ *
+ * Plan #5.05 (2026-05-25): use with @Inject(JOBS_SERVICE) in
+ * lifecycle/* NestJS providers. apps/api/src/platform-contracts.module.ts
+ * (T5) binds the token to the concrete JobsService instance via
+ * `useExisting:` so DI graph stays single-rooted.
+ *
+ * Namespace `@forgrit/jobs-queue/*` (NOT `@forgrit/platform/*`) so
+ * FM-C: no collision with plan #4.4's @forgrit/platform/auth/JobOwnerGuard.
+ * Each contract package gets its own Symbol.for() namespace; README
+ * documents the convention.
+ */
+export declare const JOBS_SERVICE: unique symbol;
+/**
+ * JOB_STEP_SERVICE — Symbol.for() DI token for IJobStepService.
+ *
+ * Plan #5.6 T5 (2026-05-26): added as FM-A escalation when wave-3 survey
+ * surfaced JobStepService consumption in architecture-decisions.controller.
+ * Use with @Inject(JOB_STEP_SERVICE) in lifecycle/* providers.
+ * apps/api/src/platform-contracts.module.ts binds via `useExisting:`.
+ */
+export declare const JOB_STEP_SERVICE: unique symbol;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/jobs/tokens.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOB_STEP_SERVICE = exports.JOBS_SERVICE = void 0;
+/**
+ * JOBS_SERVICE — Symbol.for() (global registry) DI token for IJobsService.
+ *
+ * Plan #5.05 (2026-05-25): use with @Inject(JOBS_SERVICE) in
+ * lifecycle/* NestJS providers. apps/api/src/platform-contracts.module.ts
+ * (T5) binds the token to the concrete JobsService instance via
+ * `useExisting:` so DI graph stays single-rooted.
+ *
+ * Namespace `@forgrit/jobs-queue/*` (NOT `@forgrit/platform/*`) so
+ * FM-C: no collision with plan #4.4's @forgrit/platform/auth/JobOwnerGuard.
+ * Each contract package gets its own Symbol.for() namespace; README
+ * documents the convention.
+ */
+exports.JOBS_SERVICE = Symbol.for('@forgrit/jobs-queue/JobsService');
+/**
+ * JOB_STEP_SERVICE — Symbol.for() DI token for IJobStepService.
+ *
+ * Plan #5.6 T5 (2026-05-26): added as FM-A escalation when wave-3 survey
+ * surfaced JobStepService consumption in architecture-decisions.controller.
+ * Use with @Inject(JOB_STEP_SERVICE) in lifecycle/* providers.
+ * apps/api/src/platform-contracts.module.ts binds via `useExisting:`.
+ */
+exports.JOB_STEP_SERVICE = Symbol.for('@forgrit/jobs-queue/JobStepService');
+//# sourceMappingURL=tokens.js.map

package/dist/jobs/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * IJobsService — minimum-surface contract for the subset of
+ * apps/api/src/jobs/jobs.service.ts JobsService public methods that
+ * the wave-3 blueprint freeze set (plan #5.6) actually uses.
+ *
+ * Surface (per T1 grep survey on plan/exec-2026-05-25-blueprint-w1):
+ *   - createStep            — called 4× in blueprint.worker.ts,
+ *                             1× in architecture/architecture.worker.ts
+ *   - getJob                — called 2× in architecture/architecture-decisions.controller.ts
+ *   - getFrozenPrompt       — called 1× in architecture/architecture-decisions.controller.ts
+ *
+ * Plan #5.05 (2026-05-25): contracted so the 6 wave-3 freeze files
+ * (blueprint.module.ts, blueprint.worker.ts, blueprint.service.ts,
+ * blueprint-codegen-bridge.ts, architecture-decisions.controller.ts,
+ * architecture.worker.ts, contract.worker.ts) can satisfy §1A.b
+ * without reaching into apps/api/src/jobs/jobs.service.ts at runtime.
+ *
+ * Method signatures use loose typing (Record<string, unknown> for
+ * inputs, Promise<unknown> for outputs) following plan #4.4's
+ * IPrismaService precedent — the full Prisma generic-arg machinery
+ * is too heavy to mirror by hand and would force lifecycle/* to
+ * depend on @prisma/client (defeating the contract). Call sites in
+ * lifecycle/* keep their own narrow types via TS inference at the
+ * assignment line. The `type` parameter corresponds to the StepType
+ * enum (sourced from apps/api/src/jobs/jobs.types.ts); contract uses
+ * `string` for portability, consumers narrow via the enum at the
+ * call site.
+ *
+ * If wave-3 execution surfaces a new JobsService method the freeze
+ * set needs (unlikely — survey was exhaustive — but possible if a
+ * dependency surfaces during plan #5.6's mechanical move), extend
+ * this interface in the SAME commit as plan #5.6. README documents
+ * the discipline.
+ */
+/**
+ * IJobStepService — minimum-surface contract for the subset of
+ * apps/api/src/jobs/job-step.service.ts JobStepService public methods
+ * the wave-3 blueprint freeze set actually uses.
+ *
+ * Surface (per plan #5.6 T1 survey):
+ *   - updateStep         — called 1× in architecture-decisions.controller.ts
+ *   - listStepsForJob    — called 1× in architecture-decisions.controller.ts
+ *
+ * Plan #5.6 T5 (2026-05-26): added as FM-A escalation. Plan #5.05 originally
+ * contracted only JobsService + QueueService; the T1 survey surfaced
+ * JobStepService as a wave-3 dependency in architecture-decisions.controller.
+ * Same-commit extension keeps the wave-3 controller compatible with §1A.b.
+ *
+ * Loose typing follows IJobsService precedent — concrete callers in
+ * lifecycle/* retain narrow types via TS inference.
+ */
+export interface IJobStepService {
+    /**
+     * Update a JobStep row. `update` is loosely typed as Record<string, unknown>
+     * for portability — concrete callers narrow via TS inference at the
+     * assignment line. Typical use: persist outputJson + status transitions.
+     */
+    updateStep(stepId: string, update: Record<string, unknown>): Promise<unknown>;
+    /**
+     * List all JobSteps for a job. Returns step rows ordered by createdAt
+     * (per the concrete service's default ordering). Returns [] if no steps.
+     */
+    listStepsForJob(jobId: string): Promise<unknown[]>;
+}
+export interface IJobsService {
+    /**
+     * Create a JobStep. Increments attempt count for (jobId, type) pairs.
+     *
+     * `type` corresponds to the StepType enum (currently sourced from
+     * apps/api/src/jobs/jobs.types.ts). Contract uses `string` for
+     * portability; consumers narrow via the enum at the call site.
+     *
+     * `inputJson` is opaque per-step input; the concrete service casts
+     * it to Prisma.InputJsonValue.
+     *
+     * Returns the created JobStep row. Loosely typed for the same
+     * reason as IPrismaService — concrete callers retain narrow types
+     * via inference at the assignment line.
+     */
+    createStep(jobId: string, type: string, inputJson: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Fetch a job by id including its steps relation (ordered by
+     * createdAt desc). Returns null if the job doesn't exist (does NOT
+     * throw — see `getJobOrThrow` in the concrete service for the
+     * throwing variant, which is NOT in this contract).
+     */
+    getJob(jobId: string): Promise<unknown | null>;
+    /**
+     * Fetch a FrozenPrompt by its promptId (the business-key column,
+     * not the row id). Returns null if not found.
+     */
+    getFrozenPrompt(promptId: string): Promise<unknown | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/jobs/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/queue/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './tokens';
+//# sourceMappingURL=index.d.ts.map

package/dist/queue/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./tokens"), exports);
+//# sourceMappingURL=index.js.map

package/dist/queue/tokens.d.ts

@@ -0,0 +1,14 @@
+/**
+ * QUEUE_SERVICE — Symbol.for() (global registry) DI token for IQueueService.
+ *
+ * Plan #5.05 (2026-05-25): use with @Inject(QUEUE_SERVICE) in
+ * lifecycle/* NestJS providers. apps/api/src/platform-contracts.module.ts
+ * (T5) binds the token to the concrete QueueService instance via
+ * `useExisting:` so the singleton BullMQ Queue + Worker + in-memory
+ * fallback array are preserved.
+ *
+ * Namespace `@forgrit/jobs-queue/*` (NOT `@forgrit/platform/*`) — see
+ * jobs/tokens.ts for the namespace convention rationale.
+ */
+export declare const QUEUE_SERVICE: unique symbol;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/queue/tokens.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUEUE_SERVICE = void 0;
+/**
+ * QUEUE_SERVICE — Symbol.for() (global registry) DI token for IQueueService.
+ *
+ * Plan #5.05 (2026-05-25): use with @Inject(QUEUE_SERVICE) in
+ * lifecycle/* NestJS providers. apps/api/src/platform-contracts.module.ts
+ * (T5) binds the token to the concrete QueueService instance via
+ * `useExisting:` so the singleton BullMQ Queue + Worker + in-memory
+ * fallback array are preserved.
+ *
+ * Namespace `@forgrit/jobs-queue/*` (NOT `@forgrit/platform/*`) — see
+ * jobs/tokens.ts for the namespace convention rationale.
+ */
+exports.QUEUE_SERVICE = Symbol.for('@forgrit/jobs-queue/QueueService');
+//# sourceMappingURL=tokens.js.map

package/dist/queue/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * IQueueService — minimum-surface contract for the subset of
+ * apps/api/src/queue/queue.service.ts QueueService public methods
+ * the wave-3 blueprint freeze set actually uses.
+ *
+ * Surface (per T1 grep survey):
+ *   - enqueue  — called 6× in blueprint.worker.ts,
+ *                1× in architecture/architecture.worker.ts
+ *
+ * Plan #5.05 (2026-05-25): contracted so the wave-3 freeze set can
+ * satisfy §1A.b without importing the QueueService class.
+ *
+ * Notably OUT of contract (NOT consumed by wave-3 freeze set):
+ *   - getQueueMetrics, getWorkerHealth, startWorker, moveToDlq,
+ *     getDlqEntries, requeueFromDlq, bulkRequeueFromDlq,
+ *     purgeOldDlqEntries, getDlqStats, dailyDlqCleanup,
+ *     onModuleInit, onModuleDestroy
+ *   - BullMQ types (Queue, Worker, Job) — implementation detail
+ *   - QueueMetrics, DlqEntry interfaces — admin/ops surfaces, not
+ *     consumed by blueprint
+ *
+ * When a future lifecycle module needs DLQ or metrics, extend this
+ * interface in the SAME commit. README documents the discipline.
+ */
+export interface IQueueService {
+    /**
+     * Enqueue a JobStep for processing.
+     *
+     * In Redis mode: adds to BullMQ with priority derived from stepType.
+     * In memory mode: pushes to in-memory FIFO.
+     *
+     * The terminal-job guard inside the concrete QueueService silently
+     * skips enqueue if the parent job is in a terminal state
+     * (FAILED/CODEGEN_FAILED/BLUEPRINT_FAILED/CODEGEN_FROZEN/COMPLETED) —
+     * callers do NOT need to pre-check. Returns void (never throws).
+     *
+     * `stepType` is optional; when omitted the concrete service looks
+     * it up via Prisma. Pass it when known (callers in the wave-3 set
+     * always have it from the just-created JobStep).
+     */
+    enqueue(stepId: string, stepType?: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/queue/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@forgrit/shared-contracts-jobs-queue",
+  "version": "0.1.0",
+  "description": "Type-only contracts + NestJS DI Symbol tokens for ForGrit job + queue services — IJobsService, IQueueService, IJobStepService.",
+  "keywords": [
+    "contracts",
+    "types",
+    "nestjs",
+    "jobs",
+    "queue",
+    "bullmq",
+    "forgrit"
+  ],
+  "license": "MIT",
+  "author": "ForGrit AI <forgritai@gmail.com>",
+  "homepage": "https://github.com/forgrit-ai/forgrit/tree/main/shared/contracts-jobs-queue",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgrit-ai/forgrit.git",
+    "directory": "shared/contracts-jobs-queue"
+  },
+  "bugs": {
+    "url": "https://github.com/forgrit-ai/forgrit/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./jobs": {
+      "types": "./dist/jobs/index.d.ts",
+      "default": "./dist/jobs/index.js"
+    },
+    "./queue": {
+      "types": "./dist/queue/index.d.ts",
+      "default": "./dist/queue/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@forgrit/tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json"
+  }
+}