@nodii/approval 0.0.1 → 0.1.4

package/dist/telemetry-shim.d.ts

@@ -0,0 +1,35 @@
+declare const METRIC_FAMILY_REQUEST: "request_handler";
+declare const METRIC_FAMILY_WORKER: "async_worker";
+interface AuditEmitArgs {
+    /** Pass null when no tenant context is available (e.g. completion event
+     *  for an unknown task_id). Downstream audit-chain queries filtering by
+     *  tenant_id treat null correctly; literal strings like "unknown" would
+     *  mingle with real tenant values. */
+    tenantId: string | null;
+    action: string;
+    targetKind?: string;
+    targetId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Emit a single audit row via @nodii/telemetry. Best-effort: errors do
+ *  not propagate to the caller — but the FIRST failure per process
+ *  warn-logs so operators see the wiring gap. */
+export declare function emitAudit(args: AuditEmitArgs): void;
+interface MetricInc {
+    name: string;
+    family: typeof METRIC_FAMILY_REQUEST | typeof METRIC_FAMILY_WORKER;
+    labels: Record<string, string | number>;
+    by?: number;
+}
+export declare function inc(args: MetricInc): void;
+interface HistObs {
+    name: string;
+    family: typeof METRIC_FAMILY_REQUEST | typeof METRIC_FAMILY_WORKER;
+    labels: Record<string, string | number>;
+    value: number;
+}
+export declare function observe(args: HistObs): void;
+/** Test-only reset for the warn ledger so each test starts clean. */
+export declare function _resetWarnLedgerForTests(): void;
+export { METRIC_FAMILY_REQUEST, METRIC_FAMILY_WORKER };
+//# sourceMappingURL=telemetry-shim.d.ts.map

package/dist/telemetry-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-shim.d.ts","sourceRoot":"","sources":["../src/telemetry-shim.ts"],"names":[],"mappings":"AAoBA,QAAA,MAAM,qBAAqB,EAAG,iBAA0B,CAAC;AACzD,QAAA,MAAM,oBAAoB,EAAG,cAAuB,CAAC;AAgBrD,UAAU,aAAa;IACrB;;;0CAGsC;IACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;iDAEiD;AACjD,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAuBnD;AAED,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,qBAAqB,GAAG,OAAO,oBAAoB,CAAC;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IACxC,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAUzC;AAED,UAAU,OAAO;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,qBAAqB,GAAG,OAAO,oBAAoB,CAAC;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAU3C;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C;AAED,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/telemetry-shim.js

@@ -0,0 +1,88 @@
+// Telemetry + audit emission shim per spec § 5.15.
+//
+// v0.1.0 posture:
+//   - audit.emit goes through @nodii/telemetry's `audit.emit({action,
+//     target_kind, target_id, payload})` per the audit.ts surface.
+//     Tenant_id flows in via `payload.tenant_id`; request_id, intent_id
+//     flow from the telemetry NodiiContext so we do NOT pass them inline.
+//   - Metrics are wired against @nodii/telemetry's vocabulary registry.
+//     Adopting services register the metric names from spec § 5.15 in
+//     their telemetry init's `vocabularyRegistry`. When unregistered,
+//     `MetricVocabularyError` is thrown — we catch at this boundary so
+//     a missing-vocab registration on the consumer side does not break
+//     the request path. The first swallow per metric name emits a
+//     warn-log via console.warn so adopters DO see the gap (the lib
+//     does NOT silently no-op forever).
+//
+// No Noop default. Real audit emission goes through the wired writer.
+import { audit, metrics } from "@nodii/telemetry";
+const METRIC_FAMILY_REQUEST = "request_handler";
+const METRIC_FAMILY_WORKER = "async_worker";
+/** Per-process one-shot warn ledger. Each metric name warn-logs once. */
+const WARNED_METRICS = new Set();
+let AUDIT_EMIT_FAILED_WARNED = false;
+function warnOnce(metricName, err) {
+    if (WARNED_METRICS.has(metricName))
+        return;
+    WARNED_METRICS.add(metricName);
+    const msg = err instanceof Error ? err.message : String(err);
+    // biome-ignore lint/suspicious/noConsole: best-effort warn for missing vocab registration
+    console.warn(`[@nodii/approval] metric '${metricName}' swallowed: ${msg}. Register the approval metric vocabulary per spec § 5.15 in your initTelemetry({ vocabularyRegistry }) call. Further swallows of this metric will be silent.`);
+}
+/** Emit a single audit row via @nodii/telemetry. Best-effort: errors do
+ *  not propagate to the caller — but the FIRST failure per process
+ *  warn-logs so operators see the wiring gap. */
+export function emitAudit(args) {
+    // Fire-and-forget. `audit.emit` returns a Promise; we intentionally
+    // do not await it so the request path stays low-latency. The writer
+    // wired by the adopting service is responsible for buffering + retry.
+    void (async () => {
+        try {
+            await audit.emit({
+                action: args.action,
+                target_kind: args.targetKind ?? "",
+                target_id: args.targetId ?? null,
+                payload: { tenant_id: args.tenantId, ...(args.metadata ?? {}) },
+            });
+        }
+        catch (err) {
+            if (!AUDIT_EMIT_FAILED_WARNED) {
+                AUDIT_EMIT_FAILED_WARNED = true;
+                const msg = err instanceof Error ? err.message : String(err);
+                // biome-ignore lint/suspicious/noConsole: best-effort warn for audit-writer wiring gap
+                console.warn(`[@nodii/approval] audit.emit threw: ${msg}. Further audit failures will be silent. Wire an audit writer via initTelemetry({ auditWriter }) or @nodii/audit-chain's createChainAdapter.`);
+            }
+        }
+    })();
+}
+export function inc(args) {
+    try {
+        const handle = metrics.counter(args.name, {
+            family: args.family,
+            description: `@nodii/approval counter ${args.name}`,
+        });
+        handle.inc(args.by ?? 1, args.labels);
+    }
+    catch (err) {
+        warnOnce(args.name, err);
+    }
+}
+export function observe(args) {
+    try {
+        const handle = metrics.histogram(args.name, {
+            family: args.family,
+            description: `@nodii/approval histogram ${args.name}`,
+        });
+        handle.record(args.value, args.labels);
+    }
+    catch (err) {
+        warnOnce(args.name, err);
+    }
+}
+/** Test-only reset for the warn ledger so each test starts clean. */
+export function _resetWarnLedgerForTests() {
+    WARNED_METRICS.clear();
+    AUDIT_EMIT_FAILED_WARNED = false;
+}
+export { METRIC_FAMILY_REQUEST, METRIC_FAMILY_WORKER };
+//# sourceMappingURL=telemetry-shim.js.map

package/dist/telemetry-shim.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,279 @@
+import type { Redis as IoRedis } from "ioredis";
+/** Generic SQL client surface — postgres.js-shaped, broad enough to cover
+ *  both the pool handle and the in-transaction handle.
+ *  biome-ignore lint/suspicious/noExplicitAny: porsager/postgres template-string overloads are wide. */
+export type SqlExecArgs = readonly unknown[];
+export type SqlExecResult = any;
+export interface SqlExecutor {
+    unsafe(sql: string, args?: SqlExecArgs): Promise<SqlExecResult>;
+}
+export type SqlTxExecutor = SqlExecutor;
+export interface SqlPoolExecutor extends SqlExecutor {
+    /** Run `fn` inside a single transaction (BEGIN/COMMIT/ROLLBACK). */
+    begin<T>(fn: (tx: SqlTxExecutor) => Promise<T>): Promise<T>;
+}
+/** Reserved approval-service-name namespaces, mirrored from role-catalog. */
+export declare const RESERVED_SERVICE_NAMES: readonly ["platform", "system", "pii", "audit", "dsar"];
+export type ReservedServiceName = (typeof RESERVED_SERVICE_NAMES)[number];
+/** Input shape for one entry in `defineApprovalKinds({...})`. */
+export interface ApprovalKindDefInput {
+    /** Lowercase + underscores; no dots; matches role-catalog's permission-segment rule. */
+    resource: string;
+    /** Lowercase + underscores; no dots. */
+    verb: string;
+    /** Human-readable description; surfaced into task-tracking. */
+    description?: string;
+    /**
+     * Role declared in the module's role-catalog. Library cross-checks at
+     * `initApproval` time — `ApproverRoleNotInCatalog` on mismatch.
+     */
+    approverRole: string;
+    /** Default true. ON => task created when no tenant policy row. */
+    optInDefault?: boolean;
+    /** Default false. When true + requester is in approver_role => short-circuit. */
+    selfActionAllowed?: boolean;
+    /** Override the global default expiry. */
+    expirySeconds?: number;
+    /** Optional override for the task-tracking action-button label. */
+    actionButtonLabel?: string;
+}
+/** Fully-resolved kind def stored in the runtime registry. */
+export interface ApprovalKindDef {
+    /** Short kind without the service prefix: `<resource>.<verb>`. */
+    shortKind: string;
+    /** Fully-qualified kind: `<service>.<resource>.<verb>`. */
+    kind: string;
+    resource: string;
+    verb: string;
+    description: string;
+    approverRole: string;
+    optInDefault: boolean;
+    selfActionAllowed: boolean;
+    expirySeconds: number | undefined;
+    actionButtonLabel: string | undefined;
+}
+/** Result of `defineApprovalKinds<K, T>(serviceName, defs)`. */
+export type DefinedKindMap<S extends string, T extends Record<string, ApprovalKindDefInput>> = {
+    [Name in keyof T]: ApprovalKindDef & {
+        kind: `${S}.${T[Name]["resource"]}.${T[Name]["verb"]}`;
+    };
+};
+/** Handler triple registered per kind. */
+export interface HandlerSet {
+    onApproved: (ctx: HandlerContext) => Promise<void>;
+    onRejected: (ctx: HandlerContext) => Promise<void>;
+    onExpired: (ctx: HandlerContext) => Promise<void>;
+}
+/** Sentinel used when the lib short-circuits the request flow. */
+export type ApproverKind = "user" | "audit_trail_only" | "self_action";
+/** Context passed to every handler invocation. */
+export interface HandlerContext {
+    tenantId: string;
+    deferredActionId: string;
+    deferredActionPayload: Record<string, unknown>;
+    requesterMembershipId: string;
+    approverMembershipId: string | null;
+    approverNote: string | null;
+    approverKind: ApproverKind;
+    kind: string;
+    metadata: Record<string, unknown>;
+}
+/** `requestApproval` input. */
+export interface RequestApprovalOpts {
+    kind: string;
+    tenantId: string;
+    requesterMembershipId: string;
+    idempotencyKey: string;
+    /** Arbitrary JSON — library serialises + persists. */
+    deferredActionPayload: Record<string, unknown>;
+    /** Surfaced into task-tracking's `task.metadata`. */
+    metadata?: Record<string, unknown>;
+    /** Override per-call (rare — prefer kind-level default). */
+    expirySeconds?: number;
+    /**
+     * Saga id (optional). If omitted, library generates a deterministic
+     * synthetic saga id from `(kind, idempotencyKey)`.
+     */
+    sagaId?: string;
+    /** Optional task-tracking action-button override. */
+    actionButton?: {
+        label: string;
+        moduleKey: string;
+        actionKey: string;
+        params: Record<string, unknown>;
+    };
+}
+/** `requestApproval` return value. */
+export type RequestApprovalResultStatus = "task_created" | "self_action_executed" | "opt_in_disabled_executed" | "duplicate";
+export interface RequestApprovalResult {
+    approvalId: string;
+    taskId: string | null;
+    status: RequestApprovalResultStatus;
+}
+/** Membership lookup function — service provides per its own RBAC store. */
+export type MembershipRolesLookup = (tenantId: string, membershipId: string) => Promise<readonly string[]>;
+/**
+ * gRPC client surface for `nodii-task-tracking.TaskService.CreateTask`.
+ * Library accepts an injectable client so integration tests can swap in
+ * an in-process implementation without burning proto codegen cycles.
+ * Production wiring: provide `taskServiceUrl` + library constructs a real
+ * grpc-js client wrapped with `@nodii/grpc-auth`'s S2S interceptor.
+ */
+export interface TaskServiceClient {
+    createTask(req: CreateTaskRequest): Promise<CreateTaskResponse>;
+    /** Optional — for graceful shutdown. */
+    close?: () => Promise<void>;
+}
+export interface CreateTaskRequest {
+    tenantId: string;
+    kind: string;
+    title: string;
+    description: string;
+    assigneeRole: string;
+    metadata: Record<string, unknown>;
+    /** ISO8601 timestamp. */
+    expiresAt: string;
+    idempotencyKey: string;
+    sourceModule: string;
+    actionButton: {
+        label: string;
+        moduleKey: string;
+        actionKey: string;
+        params: Record<string, unknown>;
+    };
+}
+export interface CreateTaskResponse {
+    taskId: string;
+}
+/** Inbound completion event shape. Library is transport-agnostic — the
+ *  consumer is responsible for decoding the BullMQ job payload into this
+ *  type. */
+export interface TaskCompletedEvent {
+    /** Unique event id used for dedupe via `consumed_events`. */
+    eventId: string;
+    /** Source topic — always `tasks.task.completed.v1` in v0.1.0. */
+    topic: string;
+    /** Source task id. */
+    taskId: string;
+    /** approved | rejected | expired. */
+    outcome: "approved" | "rejected" | "expired";
+    /** Kind of the original task — should start with `approval:<service>.`. */
+    kind: string;
+    /** Task-tracking-resolved completion membership. NULL on `expired`. */
+    completedByMembershipId: string | null;
+    /** Free-form note. */
+    completionNote: string | null;
+    /** Task-tracking payload metadata (carries `approvalId`, `deferredActionId`). */
+    metadata: Record<string, unknown>;
+    /** ISO8601 — when task-tracking published. */
+    publishedAt?: string;
+}
+/** Resolved tenant-policy for one kind. */
+export interface ResolvedPolicy {
+    enabled: boolean;
+    approverRole: string;
+    expirySeconds: number;
+    thresholdParams: Record<string, unknown> | null;
+    /** True when no per-tenant row exists; library used kind defaults. */
+    fallthrough: boolean;
+}
+/** `initApproval` config (spec § 5.1). */
+export interface InitApprovalConfig {
+    serviceName: string;
+    /**
+     * Either supply a postgres.js-shaped pool handle (raw mode) OR a db-rls
+     * instance (RLS-aware mode). At least one must be provided.
+     */
+    pgPool?: SqlPoolExecutor;
+    /** Optional db-rls handle (when wired). Both can coexist; rls wins. */
+    dbRls?: DbRlsLike;
+    redis: IoRedis;
+    /** Task-tracking gRPC URL. Ignored if `taskServiceClient` is provided. */
+    taskServiceUrl?: string;
+    /** Test-only override — supersedes `taskServiceUrl`. */
+    taskServiceClient?: TaskServiceClient;
+    /** Production knob: pass through to the internally-constructed
+     *  `TaskTrackingGrpcClient` when `taskServiceUrl` is set. This is how
+     *  adopting services layer in `@nodii/grpc-auth`'s S2S interceptor +
+     *  TLS credentials + per-RPC deadline without bypassing initApproval. */
+    taskClientOptions?: {
+        interceptors?: ReadonlyArray<import("@grpc/grpc-js").Interceptor>;
+        credentials?: import("@grpc/grpc-js").ChannelCredentials;
+        deadlineMs?: number;
+    };
+    /** Service that publishes the kind-set this lib enforces. */
+    membershipRolesLookup: MembershipRolesLookup;
+    /** Default expiry across kinds without their own override. */
+    defaultExpirySeconds?: number;
+    /** BullMQ lease TTL for the completion consumer. */
+    consumerLeaseSeconds?: number;
+    /** Retry budget for completion-event handler failures. */
+    consumerMaxRetries?: number;
+    /** Module's permission catalog (used for approverRole cross-check). */
+    knownRoles?: readonly string[];
+    /** Optional structured logger. */
+    logger?: {
+        warn: (msg: string, fields?: Record<string, unknown>) => void;
+        info: (msg: string, fields?: Record<string, unknown>) => void;
+        error: (msg: string, fields?: Record<string, unknown>) => void;
+    };
+}
+/** Minimal db-rls surface used by the lib. The real `@nodii/db-rls` exposes
+ *  more — we only depend on `withSystemContext({tenantId}, fn)`. */
+export interface DbRlsLike {
+    withSystemContext<T>(args: {
+        tenantId: string;
+    }, fn: (tx: SqlPoolExecutor) => Promise<T>): Promise<T>;
+    pool: SqlPoolExecutor;
+}
+/** Process-global resolved config. */
+export interface ResolvedApprovalConfig {
+    serviceName: string;
+    pgPool: SqlPoolExecutor;
+    dbRls: DbRlsLike | undefined;
+    redis: IoRedis;
+    taskServiceClient: TaskServiceClient;
+    membershipRolesLookup: MembershipRolesLookup;
+    defaultExpirySeconds: number;
+    consumerLeaseSeconds: number;
+    consumerMaxRetries: number;
+    knownRoles: ReadonlySet<string>;
+    logger: NonNullable<InitApprovalConfig["logger"]>;
+}
+/** Deferred-action row shape, mirroring `<service>_deferred_actions`. */
+export interface DeferredActionRow {
+    id: string;
+    tenant_id: string;
+    kind: string;
+    requester_membership_id: string;
+    deferred_action_payload: Record<string, unknown>;
+    status: "pending" | "approved" | "rejected" | "expired" | "executed" | "failed";
+    task_id: string | null;
+    approver_membership_id: string | null;
+    approver_note: string | null;
+    requested_at: string;
+    decided_at: string | null;
+    executed_at: string | null;
+    failed_reason: string | null;
+    idempotency_key: string;
+    audit_correlation_id: string | null;
+    metadata: Record<string, unknown>;
+}
+/** Approval-policy row shape, mirroring `<service>_approval_policies`. */
+export interface ApprovalPolicyRow {
+    id: string;
+    tenant_id: string;
+    kind: string;
+    enabled: boolean;
+    approver_role: string;
+    threshold_params: Record<string, unknown> | null;
+    expiry_seconds: number | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Constants used by the consumer + retry budget. */
+export declare const DEFAULT_EXPIRY_SECONDS: number;
+export declare const DEFAULT_CONSUMER_LEASE_SECONDS = 30;
+export declare const DEFAULT_CONSUMER_MAX_RETRIES = 5;
+export declare const DEFAULT_IDEMPOTENCY_TTL_SECONDS: number;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,18 @@
+// Public type surface for @nodii/approval per spec § 5.1 / § 5.16.
+//
+// Structural shapes match the spec verbatim. Polyglot peers (Python +
+// Go) mirror these names in their language idioms.
+/** Reserved approval-service-name namespaces, mirrored from role-catalog. */
+export const RESERVED_SERVICE_NAMES = [
+    "platform",
+    "system",
+    "pii",
+    "audit",
+    "dsar",
+];
+/** Constants used by the consumer + retry budget. */
+export const DEFAULT_EXPIRY_SECONDS = 7 * 24 * 3600; // 7 days
+export const DEFAULT_CONSUMER_LEASE_SECONDS = 30;
+export const DEFAULT_CONSUMER_MAX_RETRIES = 5;
+export const DEFAULT_IDEMPOTENCY_TTL_SECONDS = 24 * 3600; // 24h
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,EAAE;AACF,sEAAsE;AACtE,mDAAmD;AAsBnD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,UAAU;IACV,QAAQ;IACR,KAAK;IACL,OAAO;IACP,MAAM;CACE,CAAC;AAwSX,qDAAqD;AACrD,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AAC9D,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC;AACjD,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,MAAM"}

package/dist/validation.d.ts

@@ -0,0 +1,5 @@
+export declare function validateServiceName(serviceName: string, opts?: {
+    bypassReservedNamespaceCheck?: boolean;
+}): void;
+export declare function validatePermissionSegment(value: string, which: "resource" | "verb"): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAgBA,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE;IAAE,4BAA4B,CAAC,EAAE,OAAO,CAAA;CAAO,GACpD,IAAI,CA+BN;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,GAAG,MAAM,GACzB,IAAI,CAsBN"}

package/dist/validation.js

@@ -0,0 +1,40 @@
+// Validators for service name + resource + verb segments per spec § 5.3.
+// Reuses role-catalog's segment shape regex so the two surfaces stay in
+// lockstep.
+import { InvalidApprovalSegment, ReservedServiceNameViolation } from "./errors";
+import { RESERVED_SERVICE_NAMES } from "./types";
+/** Segment regex: lowercase, first char alpha, alnum + underscore only.
+ *  Kept identical to the SERVICE_NAME_RE because the service name is
+ *  interpolated unquoted into Postgres table identifiers
+ *  (`<service>_deferred_actions` etc.) — hyphens would yield invalid
+ *  SQL identifiers like `task-tracking_deferred_actions`. */
+const SEGMENT_RE = /^[a-z][a-z0-9_]*$/;
+const SERVICE_NAME_RE = /^[a-z][a-z0-9_]*$/;
+const MAX_LEN = 50;
+export function validateServiceName(serviceName, opts = {}) {
+    if (!serviceName || typeof serviceName !== "string") {
+        throw new InvalidApprovalSegment("resource", String(serviceName), "serviceName must be a non-empty string");
+    }
+    if (serviceName.length > MAX_LEN) {
+        throw new InvalidApprovalSegment("resource", serviceName, `serviceName '${serviceName}' exceeds max length ${MAX_LEN}`);
+    }
+    if (!SERVICE_NAME_RE.test(serviceName)) {
+        throw new InvalidApprovalSegment("resource", serviceName, `serviceName '${serviceName}' must match ${SERVICE_NAME_RE.source}`);
+    }
+    if (!opts.bypassReservedNamespaceCheck &&
+        RESERVED_SERVICE_NAMES.includes(serviceName)) {
+        throw new ReservedServiceNameViolation(serviceName, RESERVED_SERVICE_NAMES);
+    }
+}
+export function validatePermissionSegment(value, which) {
+    if (!value || typeof value !== "string" || value.length === 0) {
+        throw new InvalidApprovalSegment(which, String(value), `${which} must be non-empty`);
+    }
+    if (value.length > MAX_LEN) {
+        throw new InvalidApprovalSegment(which, value, `${which} '${value}' exceeds max length ${MAX_LEN}`);
+    }
+    if (!SEGMENT_RE.test(value)) {
+        throw new InvalidApprovalSegment(which, value, `${which} '${value}' must match ${SEGMENT_RE.source} (lowercase, start with letter, alnum + underscore only)`);
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,YAAY;AAEZ,OAAO,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;6DAI6D;AAC7D,MAAM,UAAU,GAAG,mBAAmB,CAAC;AACvC,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAC5C,MAAM,OAAO,GAAG,EAAE,CAAC;AAEnB,MAAM,UAAU,mBAAmB,CACjC,WAAmB,EACnB,OAAmD,EAAE;IAErD,IAAI,CAAC,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpD,MAAM,IAAI,sBAAsB,CAC9B,UAAU,EACV,MAAM,CAAC,WAAW,CAAC,EACnB,wCAAwC,CACzC,CAAC;IACJ,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QACjC,MAAM,IAAI,sBAAsB,CAC9B,UAAU,EACV,WAAW,EACX,gBAAgB,WAAW,wBAAwB,OAAO,EAAE,CAC7D,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,sBAAsB,CAC9B,UAAU,EACV,WAAW,EACX,gBAAgB,WAAW,gBAAgB,eAAe,CAAC,MAAM,EAAE,CACpE,CAAC;IACJ,CAAC;IACD,IACE,CAAC,IAAI,CAAC,4BAA4B;QACjC,sBAA4C,CAAC,QAAQ,CAAC,WAAW,CAAC,EACnE,CAAC;QACD,MAAM,IAAI,4BAA4B,CACpC,WAAW,EACX,sBAA2C,CAC5C,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,KAAa,EACb,KAA0B;IAE1B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,sBAAsB,CAC9B,KAAK,EACL,MAAM,CAAC,KAAK,CAAC,EACb,GAAG,KAAK,oBAAoB,CAC7B,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QAC3B,MAAM,IAAI,sBAAsB,CAC9B,KAAK,EACL,KAAK,EACL,GAAG,KAAK,KAAK,KAAK,wBAAwB,OAAO,EAAE,CACpD,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,sBAAsB,CAC9B,KAAK,EACL,KAAK,EACL,GAAG,KAAK,KAAK,KAAK,gBAAgB,UAAU,CAAC,MAAM,0DAA0D,CAC9G,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nodii/approval",
-  "version": "0.0.1",
-  "description": "Placeholder for @nodii/approval — implementation lands at v0.1.0",
+  "version": "0.1.4",
+  "description": "Approval library for the Nodii microservice stack — defineApprovalKinds + requestApproval + bindApprovalHandlers + per-tenant policies + completion-event consumer + migrate-gen. Polyglot ship: TS + Python + Go in parity. Spec: planning hub docKey=approval.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,13 +12,54 @@
       "default": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "README.md",
+    "src/migrations/001-approval-policies.sql",
+    "src/migrations/002-deferred-actions.sql"
+  ],
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@grpc/grpc-js": "^1.13.0",
+    "bullmq": "^5.20.0",
+    "ioredis": "^5.4.0",
+    "postgres": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "postgres": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nodii/audit-chain": "0.2.5",
+    "@nodii/grpc-auth": "0.2.0",
+    "@nodii/idempotency": "0.2.5",
+    "@nodii/role-catalog": "0.1.3",
+    "@nodii/telemetry": "0.3.0",
+    "@grpc/grpc-js": "^1.13.0",
+    "@types/bun": "^1.3.13",
+    "bullmq": "^5.20.0",
+    "ioredis": "^5.4.0",
+    "postgres": "^3.4.0",
+    "typescript": "^5.9.3"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cognion-nucleus/nodii-libs.git",
     "directory": "ts/approval"
+  },
+  "dependencies": {
+    "@nodii/audit-chain": "0.2.5",
+    "@nodii/grpc-auth": "0.2.0",
+    "@nodii/idempotency": "0.2.5",
+    "@nodii/role-catalog": "0.1.3",
+    "@nodii/telemetry": "0.3.0"
   }
 }

package/src/migrations/001-approval-policies.sql

@@ -0,0 +1,27 @@
+-- @nodii/approval migration 001
+-- Generates the per-service `<service>_approval_policies` table per spec § 5.4.
+-- Substitute `__SERVICE__` with the adopting service's name before running.
+
+CREATE TABLE IF NOT EXISTS __SERVICE___approval_policies (
+  id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id           UUID NOT NULL,
+  kind                TEXT NOT NULL,
+  enabled             BOOLEAN NOT NULL DEFAULT true,
+  approver_role       TEXT NOT NULL,
+  threshold_params    JSONB,
+  expiry_seconds      INTEGER,
+  created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE (tenant_id, kind)
+);
+
+CREATE INDEX IF NOT EXISTS __SERVICE___approval_policies_by_tenant
+  ON __SERVICE___approval_policies (tenant_id);
+
+-- NOTE: RLS is the adopter's responsibility — this migration does NOT emit
+-- ALTER TABLE ... ENABLE ROW LEVEL SECURITY. Services with @nodii/db-rls
+-- ENABLE + FORCE RLS and add the standard 3-policy pattern (per
+-- 08-rls-doctrine § 4) via their own migration tooling — the policy
+-- predicates need the service's tenant-context GUC, which the lib does
+-- not own. Services in raw-pg mode (platform-tenant scope) leave RLS off
+-- by design.

package/src/migrations/002-deferred-actions.sql

@@ -0,0 +1,41 @@
+-- @nodii/approval migration 002
+-- Generates the per-service `<service>_deferred_actions` table per spec § 5.6.
+-- Substitute `__SERVICE__` with the adopting service's name before running.
+
+CREATE TABLE IF NOT EXISTS __SERVICE___deferred_actions (
+  id                       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id                UUID NOT NULL,
+  kind                     TEXT NOT NULL,
+  requester_membership_id  UUID NOT NULL,
+  deferred_action_payload  JSONB NOT NULL,
+  status                   TEXT NOT NULL DEFAULT 'pending',
+  task_id                  UUID,
+  approver_membership_id   UUID,
+  approver_note            TEXT,
+  requested_at             TIMESTAMPTZ NOT NULL DEFAULT now(),
+  decided_at               TIMESTAMPTZ,
+  executed_at              TIMESTAMPTZ,
+  failed_reason            TEXT,
+  idempotency_key          TEXT NOT NULL,
+  audit_correlation_id     TEXT,
+  metadata                 JSONB DEFAULT '{}'::jsonb
+);
+
+CREATE INDEX IF NOT EXISTS __SERVICE___deferred_actions_by_task
+  ON __SERVICE___deferred_actions (task_id) WHERE task_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS __SERVICE___deferred_actions_pending
+  ON __SERVICE___deferred_actions (tenant_id, kind) WHERE status = 'pending';
+
+CREATE INDEX IF NOT EXISTS __SERVICE___deferred_actions_by_idempotency
+  ON __SERVICE___deferred_actions (tenant_id, idempotency_key);
+
+-- consumed_events table — shared dedupe table per replica-consumer pattern.
+-- Idempotent CREATE allows multiple nodii-libs adoptions to coexist without
+-- conflict.
+CREATE TABLE IF NOT EXISTS consumed_events (
+  event_id   TEXT NOT NULL,
+  topic      TEXT NOT NULL,
+  consumed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (event_id, topic)
+);