@mantajs/core 0.1.7 → 0.2.0-beta.0

package/dist/ports/workflow-store.d.ts

@@ -0,0 +1,111 @@
+export type WorkflowStatus = 'pending' | 'running' | 'paused' | 'succeeded' | 'failed' | 'cancelled';
+export type StepStatus = 'pending' | 'running' | 'paused' | 'succeeded' | 'failed' | 'cancelled' | 'compensated';
+export interface StepState {
+    name: string;
+    status: StepStatus;
+    started_at?: Date;
+    completed_at?: Date;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    /**
+     * Resume state written by `ctx.yield(state)`. Populated only when the step
+     * is paused mid-execution; consumed by the next invocation's handler via
+     * `ctx.resumeState` on resume, and cleared on successful completion.
+     */
+    resume_state?: unknown;
+}
+export interface WorkflowError {
+    message: string;
+    code?: string;
+    stack?: string;
+}
+export interface WorkflowRun {
+    id: string;
+    command_name: string;
+    status: WorkflowStatus;
+    steps: StepState[];
+    input: unknown;
+    output?: unknown;
+    error?: WorkflowError;
+    started_at: Date;
+    completed_at?: Date;
+    cancel_requested_at?: Date;
+}
+export interface NewWorkflowRun {
+    id: string;
+    command_name: string;
+    steps: StepState[];
+    input: unknown;
+}
+/**
+ * Durable workflow run store contract.
+ * Adapters: DrizzleWorkflowStore (Postgres).
+ *
+ * Writes only happen on state transitions (workflow started, step state change,
+ * workflow terminal). In-flight progress is NOT stored here — see IProgressChannelPort.
+ */
+export interface IWorkflowStorePort {
+    /**
+     * Insert a new run in status='pending' with the initial steps array.
+     * Throws if a run with the same id already exists.
+     */
+    create(run: NewWorkflowRun): Promise<void>;
+    /**
+     * Patch the matching step (by name) within the steps array.
+     * Preserves other steps. Undefined fields in `patch` are not overwritten.
+     *
+     * **Append-on-miss semantics** — if no step with `stepName` exists in the current
+     * `steps` array, the adapter MUST append a new `StepState { name: stepName, ...patch }`
+     * rather than throw. This is required because:
+     *   1. Some steps (e.g. dynamically-named loop iterations) are discovered at runtime
+     *      after the initial `create()` call that seeded the steps array.
+     *   2. Parallel DAG branches may add steps outside the originally-declared order.
+     *   3. It makes the method idempotent and safe for retries.
+     *
+     * Adapters whose storage requires an explicit "insert if missing" branch (Postgres
+     * JSONB with array ops, Mongo with $push, etc.) must handle this internally.
+     * See DrizzleWorkflowStore for the reference implementation.
+     */
+    updateStep(runId: string, stepName: string, patch: Partial<StepState>): Promise<void>;
+    /**
+     * Transition the overall workflow status. Optional terminal fields
+     * (output, error, completed_at) are written atomically with the status.
+     */
+    updateStatus(runId: string, status: WorkflowStatus, fields?: {
+        output?: unknown;
+        error?: WorkflowError;
+        completed_at?: Date;
+    }): Promise<void>;
+    /**
+     * Request cancellation of a running workflow.
+     * Sets `cancel_requested_at = now()` once. Idempotent — no-op if the run
+     * is already terminal (succeeded/failed/cancelled) or already cancel-requested.
+     */
+    requestCancel(runId: string): Promise<void>;
+    /**
+     * Fetch a run by id. Returns null if not found.
+     */
+    get(runId: string): Promise<WorkflowRun | null>;
+    /**
+     * List runs in a pre-terminal state ('pending' or 'running') with
+     * heartbeat_at older than the threshold. Used by the orphan-reaper job on
+     * serverless hosts (WP-F04): the host is no longer alive so the reaper
+     * flips the run to failed. Covers both statuses because workflows live as
+     * 'pending' from create() through every step until a terminal updateStatus;
+     * a crash before the first step leaves the row frozen at 'pending'.
+     */
+    listOrphans(opts: {
+        olderThan: Date;
+        limit?: number;
+    }): Promise<WorkflowRun[]>;
+    /**
+     * Mark a run as failed because its host disappeared (WP-F04). Sets status='failed',
+     * error, and completed_at. Idempotent on terminal rows — a row already
+     * succeeded/failed/cancelled is not touched. Flips both 'pending' and
+     * 'running' (see listOrphans for the rationale).
+     */
+    markOrphanFailed(runId: string, error: WorkflowError): Promise<void>;
+}
+//# sourceMappingURL=workflow-store.d.ts.map

package/dist/ports/workflow-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-store.d.ts","sourceRoot":"","sources":["../../src/ports/workflow-store.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEpG,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAA;AAEhH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;IAClB,UAAU,CAAC,EAAE,IAAI,CAAA;IACjB,YAAY,CAAC,EAAE,IAAI,CAAA;IACnB,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1C;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,cAAc,CAAA;IACtB,KAAK,EAAE,SAAS,EAAE,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,UAAU,EAAE,IAAI,CAAA;IAChB,YAAY,CAAC,EAAE,IAAI,CAAA;IACnB,mBAAmB,CAAC,EAAE,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,SAAS,EAAE,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1C;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErF;;;OAGG;IACH,YAAY,CACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,aAAa,CAAC;QAAC,YAAY,CAAC,EAAE,IAAI,CAAA;KAAE,GACxE,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhB;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IAE/C;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;IAE9E;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrE"}

package/dist/ports/workflow-store.js

@@ -0,0 +1,5 @@
+// IWorkflowStorePort interface — durable store for workflow runs.
+// Powers the `/admin/_runs/:runId` page, `useCommand` polling, and cancellation.
+// See WORKFLOW_PROGRESS.md §5.1 and §9.1 for the full design.
+export {};
+//# sourceMappingURL=workflow-store.js.map

package/dist/ports/workflow-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-store.js","sourceRoot":"","sources":["../../src/ports/workflow-store.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,iFAAiF;AACjF,8DAA8D"}

package/dist/query/define-query-graph.d.ts

@@ -0,0 +1,55 @@
+import type { AuthContext } from '../auth/types';
+/**
+ * Entity name for graph access — autocompletes from codegen.
+ */
+type EntityNameArg = keyof MantaGeneratedEntities | (string & {});
+/**
+ * Per-entity access rule:
+ * - `true` — all rows, no filter
+ * - `(auth) => filters` — row-level filter based on authenticated user
+ */
+export type EntityAccessRule = true | ((auth: AuthContext) => Record<string, unknown>);
+/**
+ * Entity access map — defines which entities are accessible and how rows are scoped.
+ */
+export type EntityAccessMap = Record<string, EntityAccessRule>;
+/**
+ * Query graph definition — controls entity + row-level access for graph queries.
+ */
+export interface QueryGraphDefinition {
+    __type: 'query-graph';
+    /** '*' = wildcard (all entities, all rows). Otherwise per-entity rules. */
+    access: '*' | EntityAccessMap;
+}
+/**
+ * Define query graph access for a context.
+ *
+ * @example
+ * ```typescript
+ * // src/queries/admin/graph.ts — full access (admin/AI)
+ * export default defineQueryGraph('*')
+ *
+ * // src/queries/store/graph.ts — scoped access
+ * export default defineQueryGraph({
+ *   product: true,                                        // all products
+ *   category: true,                                       // all categories
+ *   order: (auth) => ({ customer_id: auth.id }),    // only MY orders
+ *   customer: (auth) => ({ id: auth.id }),          // only MY profile
+ * })
+ * ```
+ */
+export declare function defineQueryGraph(access: '*'): QueryGraphDefinition;
+export declare function defineQueryGraph(access: Record<EntityNameArg, EntityAccessRule>): QueryGraphDefinition;
+/**
+ * Check if an entity is allowed by the query graph definition.
+ */
+export declare function isEntityAllowed(def: QueryGraphDefinition, entity: string): boolean;
+/**
+ * Get the row-level filter for an entity, given the auth context.
+ * Returns undefined if no filter (wildcard or `true` rule).
+ * Returns the filter record if a scope function is defined.
+ * Returns null if entity is not allowed.
+ */
+export declare function getEntityFilter(def: QueryGraphDefinition, entity: string, auth: AuthContext | null): Record<string, unknown> | undefined | null;
+export {};
+//# sourceMappingURL=define-query-graph.d.ts.map

package/dist/query/define-query-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-query-graph.d.ts","sourceRoot":"","sources":["../../src/query/define-query-graph.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAGhD;;GAEG;AACH,KAAK,aAAa,GAAG,MAAM,sBAAsB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjE;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEtF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAA;IACrB,2EAA2E;IAC3E,MAAM,EAAE,GAAG,GAAG,eAAe,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,GAAG,GAAG,oBAAoB,CAAA;AACnE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,oBAAoB,CAAA;AAevG;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGlF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,oBAAoB,EACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,GAAG,IAAI,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAO5C"}

package/dist/query/define-query-graph.js

@@ -0,0 +1,59 @@
+// defineQueryGraph — Expose the query graph for a context with row-level scoping.
+//
+// Three modes:
+//   defineQueryGraph('*')                              → wildcard, full access (admin/AI)
+//   defineQueryGraph({ product: true, order: (auth) => ({ customer_id: auth.id }) })
+//                                                      → scoped per entity
+//   No defineQueryGraph = no graph query access         → useGraphQuery errors in SDK
+//
+// Usage:
+//   // src/queries/admin/graph.ts — full access
+//   export default defineQueryGraph('*')
+//
+//   // src/queries/store/graph.ts — scoped access with row-level filters
+//   export default defineQueryGraph({
+//     product: true,
+//     category: true,
+//     order: (auth) => ({ customer_id: auth.id }),
+//     customer: (auth) => ({ id: auth.id }),
+//   })
+import { MantaError } from '../errors/manta-error';
+export function defineQueryGraph(access) {
+    if (access !== '*' && (typeof access !== 'object' || access === null)) {
+        throw new MantaError('INVALID_DATA', 'defineQueryGraph() requires "*" or an entity access map');
+    }
+    if (typeof access === 'object' && Object.keys(access).length === 0) {
+        throw new MantaError('INVALID_DATA', 'defineQueryGraph() entity map cannot be empty. Use "*" for full access.');
+    }
+    return {
+        __type: 'query-graph',
+        access,
+    };
+}
+/**
+ * Check if an entity is allowed by the query graph definition.
+ */
+export function isEntityAllowed(def, entity) {
+    if (def.access === '*')
+        return true;
+    return entity in def.access;
+}
+/**
+ * Get the row-level filter for an entity, given the auth context.
+ * Returns undefined if no filter (wildcard or `true` rule).
+ * Returns the filter record if a scope function is defined.
+ * Returns null if entity is not allowed.
+ */
+export function getEntityFilter(def, entity, auth) {
+    if (def.access === '*')
+        return undefined; // no filter
+    const rule = def.access[entity];
+    if (rule === undefined)
+        return null; // not allowed
+    if (rule === true)
+        return undefined; // all rows
+    if (!auth)
+        return null; // scoped entity but no auth → blocked
+    return rule(auth);
+}
+//# sourceMappingURL=define-query-graph.js.map

package/dist/query/define-query-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-query-graph.js","sourceRoot":"","sources":["../../src/query/define-query-graph.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,EAAE;AACF,eAAe;AACf,0FAA0F;AAC1F,qFAAqF;AACrF,2EAA2E;AAC3E,sFAAsF;AACtF,EAAE;AACF,SAAS;AACT,gDAAgD;AAChD,yCAAyC;AACzC,EAAE;AACF,yEAAyE;AACzE,sCAAsC;AACtC,qBAAqB;AACrB,sBAAsB;AACtB,mDAAmD;AACnD,6CAA6C;AAC7C,OAAO;AAGP,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AA+ClD,MAAM,UAAU,gBAAgB,CAAC,MAAqD;IACpF,IAAI,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,yDAAyD,CAAC,CAAA;IACjG,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,yEAAyE,CAAC,CAAA;IACjH,CAAC;IAED,OAAO;QACL,MAAM,EAAE,aAAa;QACrB,MAAM;KACP,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAyB,EAAE,MAAc;IACvE,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAA;IACnC,OAAO,MAAM,IAAI,GAAG,CAAC,MAAM,CAAA;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAyB,EACzB,MAAc,EACd,IAAwB;IAExB,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,SAAS,CAAA,CAAC,YAAY;IACrD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC/B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA,CAAC,cAAc;IAClD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA,CAAC,WAAW;IAC/C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA,CAAC,sCAAsC;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,CAAA;AACnB,CAAC"}

package/dist/query/define-query.d.ts

@@ -0,0 +1,79 @@
+import type { z } from 'zod';
+import type { AuthContext } from '../auth/types';
+import type { ILoggerPort } from '../ports/logger';
+import type { QueryService } from './index';
+/**
+ * Query handler context — what the developer receives in the handler.
+ */
+export interface QueryHandlerContext {
+    /** QueryService for cross-module graph queries. */
+    query: QueryService;
+    /** Structured logger. */
+    log: ILoggerPort;
+    /** Authenticated user context (null if public route). */
+    auth: AuthContext | null;
+    /** Raw request headers. */
+    headers: Record<string, string | undefined>;
+}
+/**
+ * What the developer writes — a query config with a handler.
+ */
+export interface QueryConfig<TInput = unknown, TOutput = unknown> {
+    name: string;
+    description: string;
+    input: z.ZodType<TInput>;
+    handler: (input: TInput, context: QueryHandlerContext) => Promise<TOutput>;
+}
+/**
+ * Internal query definition — handler receives raw context. Used by bootstrap/registry.
+ */
+export interface QueryDefinition<TInput = unknown, TOutput = unknown> {
+    name: string;
+    description: string;
+    input: z.ZodType<TInput>;
+    handler: (input: TInput, context: QueryHandlerContext) => Promise<TOutput>;
+    __type: 'query';
+}
+/**
+ * Define a query (CQRS read side).
+ *
+ * Queries are read-only, side-effect-free operations exposed as GET endpoints.
+ * They receive the QueryService for cross-module graph queries, or can access
+ * module services directly through the app.
+ *
+ * @example
+ * ```typescript
+ * // src/queries/admin/list-products.ts
+ * import { defineQuery } from '@mantajs/core'
+ * import { z } from 'zod'
+ *
+ * export default defineQuery({
+ *   name: 'list-products',
+ *   description: 'List products with filtering and pagination',
+ *   input: z.object({
+ *     status: z.enum(['draft', 'active', 'archived']).optional(),
+ *     limit: z.number().default(20),
+ *     offset: z.number().default(0),
+ *   }),
+ *   handler: async (input, { query }) => {
+ *     return query.graph({
+ *       entity: 'product',
+ *       filters: input.status ? { status: input.status } : undefined,
+ *       pagination: { limit: input.limit, offset: input.offset },
+ *     })
+ *   },
+ * })
+ * ```
+ */
+export declare function defineQuery<TInput, TOutput>(config: QueryConfig<TInput, TOutput>): QueryDefinition<TInput, TOutput>;
+/**
+ * Registry for query definitions — analogous to CommandRegistry.
+ */
+export declare class QueryRegistry {
+    private _entries;
+    register(def: QueryDefinition): void;
+    get(name: string): QueryDefinition | undefined;
+    list(): QueryDefinition[];
+    _reset(): void;
+}
+//# sourceMappingURL=define-query.d.ts.map

package/dist/query/define-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-query.d.ts","sourceRoot":"","sources":["../../src/query/define-query.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,KAAK,EAAE,YAAY,CAAA;IACnB,yBAAyB;IACzB,GAAG,EAAE,WAAW,CAAA;IAChB,yDAAyD;IACzD,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACxB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACxB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC3E;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAClE,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACxB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1E,MAAM,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CA8BnH;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAqC;IAErD,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAOpC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI9C,IAAI,IAAI,eAAe,EAAE;IAIzB,MAAM,IAAI,IAAI;CAGf"}

package/dist/query/define-query.js

@@ -0,0 +1,77 @@
+// SPEC-V2 — defineQuery() + QueryRegistry
+// CQRS read side. Parallels defineCommand but for GET endpoints.
+import { MantaError } from '../errors/manta-error';
+/**
+ * Define a query (CQRS read side).
+ *
+ * Queries are read-only, side-effect-free operations exposed as GET endpoints.
+ * They receive the QueryService for cross-module graph queries, or can access
+ * module services directly through the app.
+ *
+ * @example
+ * ```typescript
+ * // src/queries/admin/list-products.ts
+ * import { defineQuery } from '@mantajs/core'
+ * import { z } from 'zod'
+ *
+ * export default defineQuery({
+ *   name: 'list-products',
+ *   description: 'List products with filtering and pagination',
+ *   input: z.object({
+ *     status: z.enum(['draft', 'active', 'archived']).optional(),
+ *     limit: z.number().default(20),
+ *     offset: z.number().default(0),
+ *   }),
+ *   handler: async (input, { query }) => {
+ *     return query.graph({
+ *       entity: 'product',
+ *       filters: input.status ? { status: input.status } : undefined,
+ *       pagination: { limit: input.limit, offset: input.offset },
+ *     })
+ *   },
+ * })
+ * ```
+ */
+export function defineQuery(config) {
+    if (!config.name) {
+        throw new MantaError('INVALID_DATA', 'Query name is required. Usage: defineQuery({ name: "list-products", description: "...", input: z.object({...}), handler: async (input, { query }) => {...} })');
+    }
+    if (!config.description) {
+        throw new MantaError('INVALID_DATA', `Query "${config.name}" requires a description.`);
+    }
+    if (!config.input) {
+        throw new MantaError('INVALID_DATA', `Query "${config.name}" requires an input Zod schema. Use z.object({}) for queries with no parameters.`);
+    }
+    if (typeof config.handler !== 'function') {
+        throw new MantaError('INVALID_DATA', `Query "${config.name}" handler must be an async function: handler: async (input, { query }) => {...}`);
+    }
+    return {
+        name: config.name,
+        description: config.description,
+        input: config.input,
+        handler: config.handler,
+        __type: 'query',
+    };
+}
+/**
+ * Registry for query definitions — analogous to CommandRegistry.
+ */
+export class QueryRegistry {
+    _entries = new Map();
+    register(def) {
+        if (this._entries.has(def.name)) {
+            throw new MantaError('DUPLICATE_ERROR', `Query "${def.name}" is already registered`);
+        }
+        this._entries.set(def.name, def);
+    }
+    get(name) {
+        return this._entries.get(name);
+    }
+    list() {
+        return [...this._entries.values()];
+    }
+    _reset() {
+        this._entries.clear();
+    }
+}
+//# sourceMappingURL=define-query.js.map

package/dist/query/define-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-query.js","sourceRoot":"","sources":["../../src/query/define-query.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,iEAAiE;AAIjE,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAuClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,WAAW,CAAkB,MAAoC;IAC/E,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,UAAU,CAClB,cAAc,EACd,+JAA+J,CAChK,CAAA;IACH,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,UAAU,MAAM,CAAC,IAAI,2BAA2B,CAAC,CAAA;IACxF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,UAAU,CAClB,cAAc,EACd,UAAU,MAAM,CAAC,IAAI,kFAAkF,CACxG,CAAA;IACH,CAAC;IACD,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACzC,MAAM,IAAI,UAAU,CAClB,cAAc,EACd,UAAU,MAAM,CAAC,IAAI,iFAAiF,CACvG,CAAA;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,OAAO;KAChB,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,aAAa;IAChB,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAA;IAErD,QAAQ,CAAC,GAAoB;QAC3B,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,UAAU,GAAG,CAAC,IAAI,yBAAyB,CAAC,CAAA;QACtF,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IAClC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAChC,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;IACpC,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;IACvB,CAAC;CACF"}

package/dist/query/extend-query-graph.d.ts

@@ -0,0 +1,36 @@
+import type { ILoggerPort } from '../ports/logger';
+import type { GraphQueryConfig } from './index';
+/**
+ * Context passed to an extension's resolver.
+ */
+export interface QueryGraphExtensionContext {
+    /** MantaApp instance — used to resolve plugin config and other infra */
+    app: any;
+    logger: ILoggerPort;
+}
+/**
+ * Extension resolver — receives a Manta query graph config, returns normalized rows.
+ */
+export type QueryGraphExtensionResolver = (query: GraphQueryConfig, ctx: QueryGraphExtensionContext) => Promise<Record<string, unknown>[]>;
+/**
+ * Definition of a query graph extension — what a module exports from `query-graph.ts`.
+ */
+export interface QueryGraphExtensionDefinition {
+    __type: 'query-extension';
+    /** Entity names this extension is responsible for resolving. */
+    owns: string[];
+    /** Resolver function — called by the query engine when any of the owned entities are queried. */
+    resolve: QueryGraphExtensionResolver;
+    /**
+     * Optional: filters supported by entity. Filters not in this list will throw a clear error
+     * so the caller (or AI) can adapt. Omit to mean "all filters accepted" (use at own risk).
+     */
+    supportedFilters?: Record<string, string[]>;
+    /** Module name that registered this extension (populated at bootstrap) */
+    __module?: string;
+}
+/**
+ * Declare that a module extends the query graph with resolvers for a set of external entities.
+ */
+export declare function extendQueryGraph(config: Omit<QueryGraphExtensionDefinition, '__type'>): QueryGraphExtensionDefinition;
+//# sourceMappingURL=extend-query-graph.d.ts.map

package/dist/query/extend-query-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend-query-graph.d.ts","sourceRoot":"","sources":["../../src/query/extend-query-graph.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,wEAAwE;IAExE,GAAG,EAAE,GAAG,CAAA;IACR,MAAM,EAAE,WAAW,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,CACxC,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,0BAA0B,KAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAA;AAEvC;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,iBAAiB,CAAA;IACzB,gEAAgE;IAChE,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,iGAAiG;IACjG,OAAO,EAAE,2BAA2B,CAAA;IACpC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,6BAA6B,EAAE,QAAQ,CAAC,GAAG,6BAA6B,CAerH"}

package/dist/query/extend-query-graph.js

@@ -0,0 +1,34 @@
+// extendQueryGraph — Extend the query graph with a custom resolver for external entities.
+//
+// Used by modules that own entities living in an external system (PostHog, Stripe, etc.).
+// The module declares which entities it owns and provides a resolver that translates
+// a Manta query graph into calls to the external backend.
+//
+// Unlike defineQueryGraph (which controls access per-context), extendQueryGraph ADDS
+// new resolution paths to the query engine itself.
+//
+// Example (in modules/posthog/queries/graph.ts):
+//   export default extendQueryGraph({
+//     owns: ['posthogEvent', 'posthogPerson', 'posthogInsight'],
+//     async resolve(query, ctx) {
+//       // translate query → HogQL, fetch, return normalized rows
+//     },
+//   })
+/**
+ * Declare that a module extends the query graph with resolvers for a set of external entities.
+ */
+export function extendQueryGraph(config) {
+    if (!Array.isArray(config.owns) || config.owns.length === 0) {
+        throw new Error('extendQueryGraph() requires a non-empty `owns` array listing the entity names this extension resolves.');
+    }
+    if (typeof config.resolve !== 'function') {
+        throw new Error('extendQueryGraph() requires a `resolve` function: async (query, ctx) => rows[]');
+    }
+    return {
+        __type: 'query-extension',
+        owns: config.owns,
+        resolve: config.resolve,
+        ...(config.supportedFilters ? { supportedFilters: config.supportedFilters } : {}),
+    };
+}
+//# sourceMappingURL=extend-query-graph.js.map

package/dist/query/extend-query-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend-query-graph.js","sourceRoot":"","sources":["../../src/query/extend-query-graph.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,EAAE;AACF,0FAA0F;AAC1F,qFAAqF;AACrF,0DAA0D;AAC1D,EAAE;AACF,qFAAqF;AACrF,mDAAmD;AACnD,EAAE;AACF,iDAAiD;AACjD,sCAAsC;AACtC,iEAAiE;AACjE,kCAAkC;AAClC,kEAAkE;AAClE,SAAS;AACT,OAAO;AAyCP;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAqD;IACpF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CACb,wGAAwG,CACzG,CAAA;IACH,CAAC;IACD,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,gFAAgF,CAAC,CAAA;IACnG,CAAC;IACD,OAAO;QACL,MAAM,EAAE,iBAAiB;QACzB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClF,CAAA;AACH,CAAC"}