@hotmeshio/long-tail 0.22.1 → 0.22.3

package/build/lib/db/schemas/037_scan_gtin_and_subject_grants.sql

@@ -0,0 +1,27 @@
+-- Migration 037: GTIN scan schemes and subject-bound acting grants
+--
+-- encoding 'gtin': a scheme whose codes are manufacturer barcodes (UPC-A,
+-- EAN-13, EAN-8, GTIN-14). The code carries no scheme or category; the
+-- check digit identifies it, and the scheme's single rule is category '0'.
+--
+-- grant_scope (identity kind only):
+--   'action'  each mutating act spends one use of the grant.
+--   'subject' the first act binds the grant to the held subject (the item
+--             the station is holding); further acts on that same subject do
+--             not count, and the grant cannot act on any other subject.
+--
+-- lt_ephemeral_credentials.bind_on_use / bound_ref carry that binding.
+
+ALTER TABLE lt_config_scan_schemes
+  DROP CONSTRAINT IF EXISTS lt_config_scan_schemes_encoding_check;
+ALTER TABLE lt_config_scan_schemes
+  ADD CONSTRAINT lt_config_scan_schemes_encoding_check
+    CHECK (encoding IN ('fixed', 'delimited', 'gtin'));
+
+ALTER TABLE lt_config_scan_schemes
+  ADD COLUMN IF NOT EXISTS grant_scope TEXT NOT NULL DEFAULT 'action'
+    CHECK (grant_scope IN ('action', 'subject'));
+
+ALTER TABLE lt_ephemeral_credentials
+  ADD COLUMN IF NOT EXISTS bind_on_use BOOLEAN NOT NULL DEFAULT FALSE,
+  ADD COLUMN IF NOT EXISTS bound_ref TEXT;

package/build/routes/escalations/acting.d.ts

@@ -2,6 +2,11 @@ import type { Request, Response } from 'express';
 import type { LTApiAuth } from '../../types/sdk';
 /** The header a shared station device rides its badge grant on. */
 export declare const ACTING_TOKEN_HEADER = "x-lt-acting-token";
+/**
+ * Uses the grant has left after this request spent one: a count, or
+ * `unbounded` while only the TTL limits it. The client retires its grant on 0.
+ */
+export declare const ACTING_REMAINING_HEADER = "x-lt-acting-remaining";
 /**
  * The effective actor for an escalation WORK verb (claim, release, resolve):
  * the badged person when an acting grant rides the request, otherwise the

package/build/routes/escalations/acting.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACTING_TOKEN_HEADER = void 0;
+exports.ACTING_REMAINING_HEADER = exports.ACTING_TOKEN_HEADER = void 0;
 exports.effectiveWorkAuth = effectiveWorkAuth;
 const acting_identity_1 = require("../../services/iam/acting-identity");
 /** The header a shared station device rides its badge grant on. */
 exports.ACTING_TOKEN_HEADER = 'x-lt-acting-token';
+/**
+ * Uses the grant has left after this request spent one: a count, or
+ * `unbounded` while only the TTL limits it. The client retires its grant on 0.
+ */
+exports.ACTING_REMAINING_HEADER = 'x-lt-acting-remaining';
 /**
  * The effective actor for an escalation WORK verb (claim, release, resolve):
  * the badged person when an acting grant rides the request, otherwise the
@@ -21,5 +26,7 @@ async function effectiveWorkAuth(req, res) {
         res.status(401).json({ error: resolved.error });
         return null;
     }
+    const { remaining } = resolved.grant;
+    res.setHeader(exports.ACTING_REMAINING_HEADER, remaining === null ? 'unbounded' : String(remaining));
     return resolved.auth;
 }

package/build/routes/scan-codes.js

@@ -49,6 +49,8 @@ router.post('/execute', async (req, res) => {
         code: req.body.code,
         actingToken: req.body.actingToken,
         previousActingToken: req.body.previousActingToken,
+        subject: req.body.subject,
+        stationRole: req.body.stationRole,
     }, req.auth);
     res.status(result.status).json(result.data ?? { error: result.error });
 });
@@ -102,6 +104,7 @@ router.put('/schemes/:version', auth_1.requireRoleManager, async (req, res) => {
         kind: req.body.kind,
         grant_ttl_seconds: req.body.grant_ttl_seconds,
         grant_max_uses: req.body.grant_max_uses,
+        grant_scope: req.body.grant_scope,
         enabled: req.body.enabled,
     });
     res.status(result.status).json(result.data ?? { error: result.error });

package/build/sdk/index.d.ts

@@ -213,6 +213,7 @@ export declare function createClient(options?: LTClientOptions): {
             metadata?: Record<string, any>;
             provisionIfAbsent?: import("../api/escalations/helpers").ProvisionIfAbsent;
             restrictRoles?: string[];
+            assertId?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         resolveByMetadata: (input: {
             key: string;

package/build/services/escalation/claim-asserted.d.ts

@@ -0,0 +1,10 @@
+import type { ClaimResult } from './types';
+/**
+ * Claims one named row, the same claim `claimByMetadata` makes on the row it
+ * picks: pending, the facet still matches, the role is allowed, and no live
+ * claim by someone else. One statement; a miss writes nothing.
+ * $1=filter $2=assignee $3=minutes $4=roles $5=metadata patch $6=id
+ */
+export declare const CLAIM_ASSERTED = "WITH target AS MATERIALIZED (\n  SELECT id, assigned_to AS prior_assigned_to FROM public.hmsh_escalations\n  WHERE id = $6\n    AND metadata @> $1::jsonb\n    AND ($4::text[] IS NULL OR role = ANY($4::text[]))\n    AND status = 'pending'\n    AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $2)\n  FOR UPDATE SKIP LOCKED\n)\nUPDATE public.hmsh_escalations e\nSET assigned_to      = $2,\n    claimed_at       = NOW(),\n    claim_expires_at = NOW() + ($3 * INTERVAL '1 minute'),\n    assigned_until   = NOW() + ($3 * INTERVAL '1 minute'),\n    metadata         = CASE WHEN $5::jsonb IS NOT NULL\n                            THEN COALESCE(e.metadata, '{}'::jsonb) || $5::jsonb\n                            ELSE e.metadata END,\n    updated_at       = NOW()\nFROM target WHERE e.id = target.id\nRETURNING e.*, target.prior_assigned_to\n";
+/** Claim the row `id` when it still carries `key = value`; null when it does not. */
+export declare function claimAssertedByMetadata(id: string, key: string, value: string, userId: string, durationMinutes?: number, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<ClaimResult | null>;

package/build/services/escalation/claim-asserted.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAIM_ASSERTED = void 0;
+exports.claimAssertedByMetadata = claimAssertedByMetadata;
+const db_1 = require("../../lib/db");
+const escalation_wire_1 = require("../../lib/events/escalation-wire");
+const uuid_1 = require("../../lib/uuid");
+const client_1 = require("./client");
+const crud_1 = require("./crud");
+const map_1 = require("./map");
+/**
+ * Claims one named row, the same claim `claimByMetadata` makes on the row it
+ * picks: pending, the facet still matches, the role is allowed, and no live
+ * claim by someone else. One statement; a miss writes nothing.
+ * $1=filter $2=assignee $3=minutes $4=roles $5=metadata patch $6=id
+ */
+exports.CLAIM_ASSERTED = `\
+WITH target AS MATERIALIZED (
+  SELECT id, assigned_to AS prior_assigned_to FROM public.hmsh_escalations
+  WHERE id = $6
+    AND metadata @> $1::jsonb
+    AND ($4::text[] IS NULL OR role = ANY($4::text[]))
+    AND status = 'pending'
+    AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $2)
+  FOR UPDATE SKIP LOCKED
+)
+UPDATE public.hmsh_escalations e
+SET assigned_to      = $2,
+    claimed_at       = NOW(),
+    claim_expires_at = NOW() + ($3 * INTERVAL '1 minute'),
+    assigned_until   = NOW() + ($3 * INTERVAL '1 minute'),
+    metadata         = CASE WHEN $5::jsonb IS NOT NULL
+                            THEN COALESCE(e.metadata, '{}'::jsonb) || $5::jsonb
+                            ELSE e.metadata END,
+    updated_at       = NOW()
+FROM target WHERE e.id = target.id
+RETURNING e.*, target.prior_assigned_to
+`;
+/** Claim the row `id` when it still carries `key = value`; null when it does not. */
+async function claimAssertedByMetadata(id, key, value, userId, durationMinutes = 30, metadata, allowedRoles) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
+    await (0, client_1.ensureEscalationCompatView)();
+    const { rows } = await (0, db_1.getPool)().query(exports.CLAIM_ASSERTED, [
+        JSON.stringify({ [key]: value }), userId, durationMinutes,
+        allowedRoles ?? null, metadata ? JSON.stringify(metadata) : null, id,
+    ]);
+    if (rows.length === 0)
+        return null;
+    const { prior_assigned_to: prior, ...entry } = rows[0];
+    const escalation = (0, map_1.toEscalationRecord)(entry);
+    (0, crud_1.publishEscalationChange)({
+        type: 'escalation.claimed',
+        source: 'service',
+        workflowId: escalation.workflow_id || '',
+        workflowName: escalation.workflow_type || '',
+        taskQueue: escalation.task_queue || '',
+        escalationId: escalation.id,
+        role: escalation.role,
+        status: 'claimed',
+        data: (0, escalation_wire_1.escalationEventData)(escalation),
+    });
+    return { escalation, isExtension: prior === userId };
+}

package/build/services/escalation/facets.d.ts

@@ -2,7 +2,9 @@ import type { ClaimedGroup, FacetQuery, GroupSummary, LTEscalationRecord } from
 /** Ensure the compat view + the origin_id index exist before the first query. */
 export declare function ensureFacetReady(): Promise<void>;
 /** Item-level faceted search — filter/sort over top-level columns and metadata facets. */
-export declare function searchByFacets(query: FacetQuery): Promise<{
+export declare function searchByFacets(query: FacetQuery, opts?: {
+    total?: boolean;
+}): Promise<{
     escalations: LTEscalationRecord[];
     total: number;
 }>;

package/build/services/escalation/facets.js

@@ -45,7 +45,7 @@ function ensureFacetReady() {
 }
 // ── Reads ────────────────────────────────────────────────────────────────────
 /** Item-level faceted search — filter/sort over top-level columns and metadata facets. */
-async function searchByFacets(query) {
+async function searchByFacets(query, opts = {}) {
     await ensureFacetReady();
     const pool = (0, db_1.getPool)();
     const params = [];
@@ -55,9 +55,13 @@ async function searchByFacets(query) {
     const offset = query.offset ?? 0;
     const [rows, count] = await Promise.all([
         pool.query(`SELECT * FROM public.lt_escalations WHERE ${where} ORDER BY ${order} LIMIT $${params.length + 1} OFFSET $${params.length + 2}`, [...params, limit, offset]),
-        pool.query(`SELECT count(*)::int AS total FROM public.lt_escalations WHERE ${where}`, params),
+        // A caller that only picks among a few rows skips the count.
+        opts.total === false
+            ? null
+            : pool.query(`SELECT count(*)::int AS total FROM public.lt_escalations WHERE ${where}`, params),
     ]);
-    return { escalations: (0, map_1.toEscalationRecords)(rows.rows), total: count.rows[0]?.total ?? 0 };
+    const escalations = (0, map_1.toEscalationRecords)(rows.rows);
+    return { escalations, total: count ? count.rows[0]?.total ?? 0 : escalations.length };
 }
 /**
  * Order-level view of the pond — what a batched dispatcher reads to page by

package/build/services/escalation/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export * from './crud';
+export { claimAssertedByMetadata } from './claim-asserted';
 export * from './batch';
 export * from './accumulate';
 export * from './bulk';

package/build/services/escalation/index.js

@@ -14,9 +14,11 @@ 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 });
-exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = void 0;
+exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = exports.claimAssertedByMetadata = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./crud"), exports);
+var claim_asserted_1 = require("./claim-asserted");
+Object.defineProperty(exports, "claimAssertedByMetadata", { enumerable: true, get: function () { return claim_asserted_1.claimAssertedByMetadata; } });
 __exportStar(require("./batch"), exports);
 __exportStar(require("./accumulate"), exports);
 __exportStar(require("./bulk"), exports);

package/build/services/iam/acting-identity.d.ts

@@ -1,16 +1,41 @@
 import type { LTApiAuth } from '../../types/sdk';
+/** What the client needs to know about a grant after a request touched it. */
+export interface ActingGrantState {
+    /** True when this request spent a use. */
+    consumed: boolean;
+    /** Uses left; null = bounded only by TTL (or bound to one subject). */
+    remaining: number | null;
+    /** True once the grant is bound to one subject. */
+    bound: boolean;
+}
 /** The acting-auth resolution result: an auth to act as, or the loud reason not to. */
 export type ActingAuthResult = {
     ok: true;
     auth: LTApiAuth;
+    grant: ActingGrantState;
 } | {
     ok: false;
     error: string;
 };
+export declare const ACTING_ERRORS: {
+    readonly NOT_A_GRANT: "actingToken is not an acting-identity grant";
+    readonly EXPIRED: "acting identity expired — scan your badge again";
+    readonly INACTIVE: "acting identity is no longer an active user";
+    readonly OTHER_SUBJECT: "this badge already acted on another item; scan your badge again";
+};
+/**
+ * Read a supplied acting grant without spending it. A token that fails
+ * (wrong label, expired, exhausted, or a vanished user) is a terminal error,
+ * never a silent fall-back to the session identity: that would misattribute
+ * whatever follows.
+ */
+export declare function peekActingAuth(actingToken: string): Promise<ActingAuthResult>;
 /**
- * Exchange a supplied acting grant for the person it names. A supplied token
- * that fails — wrong label, expired, exhausted, or a vanished user — is a
- * terminal error, never a silent fall-back to the session identity: that
- * would misattribute whatever follows.
+ * Spend one use of the grant for an act. `ref` names the subject the act
+ * lands on; a subject-scoped grant binds to it on first spend.
  */
+export declare function consumeActingGrant(actingToken: string, ref?: string | null): Promise<ActingAuthResult>;
+/** Return a use whose act missed. `unbind` when that spend bound the grant. */
+export declare function refundActingGrant(actingToken: string, unbind: boolean): Promise<void>;
+/** Spend the grant up front: the escalation work routes always act. */
 export declare function resolveActingAuth(actingToken: string): Promise<ActingAuthResult>;

package/build/services/iam/acting-identity.js

@@ -33,28 +33,71 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTING_ERRORS = void 0;
+exports.peekActingAuth = peekActingAuth;
+exports.consumeActingGrant = consumeActingGrant;
+exports.refundActingGrant = refundActingGrant;
 exports.resolveActingAuth = resolveActingAuth;
 const userService = __importStar(require("../user"));
 const ephemeral_1 = require("./ephemeral");
 const types_1 = require("../../types");
+exports.ACTING_ERRORS = {
+    NOT_A_GRANT: 'actingToken is not an acting-identity grant',
+    EXPIRED: 'acting identity expired — scan your badge again',
+    INACTIVE: 'acting identity is no longer an active user',
+    OTHER_SUBJECT: 'this badge already acted on another item; scan your badge again',
+};
+function isActingGrant(actingToken) {
+    const parsed = (0, ephemeral_1.parseEphemeralToken)(actingToken);
+    return parsed && parsed.label === types_1.ACTING_IDENTITY_LABEL ? parsed.uuid : null;
+}
+async function toAuth(grant, consumed) {
+    const user = await userService.getUser(grant.value);
+    if (!user || user.status !== 'active')
+        return { ok: false, error: exports.ACTING_ERRORS.INACTIVE };
+    return {
+        ok: true,
+        auth: { userId: user.id },
+        grant: { consumed, remaining: grant.remaining, bound: grant.bound },
+    };
+}
 /**
- * Exchange a supplied acting grant for the person it names. A supplied token
- * that fails — wrong label, expired, exhausted, or a vanished user — is a
- * terminal error, never a silent fall-back to the session identity: that
- * would misattribute whatever follows.
+ * Read a supplied acting grant without spending it. A token that fails
+ * (wrong label, expired, exhausted, or a vanished user) is a terminal error,
+ * never a silent fall-back to the session identity: that would misattribute
+ * whatever follows.
  */
-async function resolveActingAuth(actingToken) {
-    const parsed = (0, ephemeral_1.parseEphemeralToken)(actingToken);
-    if (!parsed || parsed.label !== types_1.ACTING_IDENTITY_LABEL) {
-        return { ok: false, error: 'actingToken is not an acting-identity grant' };
-    }
-    const userId = await (0, ephemeral_1.exchangeEphemeralToken)(actingToken);
-    if (!userId) {
-        return { ok: false, error: 'acting identity expired — scan your badge again' };
-    }
-    const user = await userService.getUser(userId);
-    if (!user || user.status !== 'active') {
-        return { ok: false, error: 'acting identity is no longer an active user' };
+async function peekActingAuth(actingToken) {
+    const uuid = isActingGrant(actingToken);
+    if (!uuid)
+        return { ok: false, error: exports.ACTING_ERRORS.NOT_A_GRANT };
+    const grant = await (0, ephemeral_1.peekEphemeral)(uuid);
+    if (!grant)
+        return { ok: false, error: exports.ACTING_ERRORS.EXPIRED };
+    return toAuth(grant, false);
+}
+/**
+ * Spend one use of the grant for an act. `ref` names the subject the act
+ * lands on; a subject-scoped grant binds to it on first spend.
+ */
+async function consumeActingGrant(actingToken, ref = null) {
+    const uuid = isActingGrant(actingToken);
+    if (!uuid)
+        return { ok: false, error: exports.ACTING_ERRORS.NOT_A_GRANT };
+    const grant = await (0, ephemeral_1.consumeEphemeral)(uuid, ref);
+    if (!grant) {
+        const live = ref ? await (0, ephemeral_1.peekEphemeral)(uuid) : null;
+        return { ok: false, error: live?.bound ? exports.ACTING_ERRORS.OTHER_SUBJECT : exports.ACTING_ERRORS.EXPIRED };
     }
-    return { ok: true, auth: { userId: user.id } };
+    return toAuth(grant, true);
+}
+/** Return a use whose act missed. `unbind` when that spend bound the grant. */
+async function refundActingGrant(actingToken, unbind) {
+    const uuid = isActingGrant(actingToken);
+    if (uuid)
+        await (0, ephemeral_1.refundEphemeral)(uuid, unbind);
+}
+/** Spend the grant up front: the escalation work routes always act. */
+async function resolveActingAuth(actingToken) {
+    return consumeActingGrant(actingToken);
 }

package/build/services/iam/ephemeral.d.ts

@@ -21,6 +21,8 @@ export interface StoreEphemeralOptions {
     ttlSeconds?: number;
     /** Human-readable label for debugging. */
     label?: string;
+    /** The first ref-carrying spend binds the token to that ref (see consumeEphemeral). */
+    bindOnUse?: boolean;
 }
 /**
  * Store a sensitive value. Returns the raw token UUID.
@@ -40,6 +42,25 @@ export declare function storeEphemeral(value: string, opts?: StoreEphemeralOptio
  * - Row is deleted when use_count reaches max_uses (if max_uses > 0)
  */
 export declare function exchangeEphemeral(token: string): Promise<string | null>;
+/** A live token's value and how many uses it has left (null = unbounded). */
+export interface EphemeralGrant {
+    value: string;
+    remaining: number | null;
+    /** True once the token is bound to a ref; it then acts only on that ref. */
+    bound: boolean;
+}
+/** Read a live token without spending a use. */
+export declare function peekEphemeral(token: string): Promise<EphemeralGrant | null>;
+/**
+ * Spend one use of a token. A token stored with `bindOnUse` binds to `ref`
+ * on its first ref-carrying spend; after that it spends freely on that ref
+ * and never on another. Returns null when expired, exhausted, or bound
+ * elsewhere. An exhausted row stays until its TTL so a spend whose act
+ * missed can be refunded.
+ */
+export declare function consumeEphemeral(token: string, ref?: string | null): Promise<EphemeralGrant | null>;
+/** Undo one spend whose act did not land. `unbind` undoes the binding that spend made. */
+export declare function refundEphemeral(token: string, unbind: boolean): Promise<void>;
 /**
  * Explicitly revoke a token before expiry/exhaustion.
  */

package/build/services/iam/ephemeral.js

@@ -7,6 +7,9 @@ exports.exchangeEphemeralToken = exchangeEphemeralToken;
 exports.exchangeTokensInArgs = exchangeTokensInArgs;
 exports.storeEphemeral = storeEphemeral;
 exports.exchangeEphemeral = exchangeEphemeral;
+exports.peekEphemeral = peekEphemeral;
+exports.consumeEphemeral = consumeEphemeral;
+exports.refundEphemeral = refundEphemeral;
 exports.revokeEphemeral = revokeEphemeral;
 exports.cleanupExpired = cleanupExpired;
 const db_1 = require("../../lib/db");
@@ -81,7 +84,7 @@ async function storeEphemeral(value, opts = {}) {
     const expiresAt = opts.ttlSeconds
         ? `NOW() + ${opts.ttlSeconds} * INTERVAL '1 second'`
         : 'NULL';
-    const { rows } = await pool.query((0, sql_1.INSERT_EPHEMERAL)(expiresAt), [Buffer.from(encrypted, 'base64'), opts.label || null, maxUses]);
+    const { rows } = await pool.query((0, sql_1.INSERT_EPHEMERAL)(expiresAt), [Buffer.from(encrypted, 'base64'), opts.label || null, maxUses, opts.bindOnUse ?? false]);
     return rows[0].token;
 }
 /**
@@ -106,6 +109,34 @@ async function exchangeEphemeral(token) {
     }
     return (0, crypto_1.decrypt)(buf.toString('base64'));
 }
+function toGrant(row) {
+    const bound = row.bound_ref !== null;
+    return {
+        value: (0, crypto_1.decrypt)(row.value.toString('base64')),
+        remaining: bound || row.max_uses === 0 ? null : Math.max(0, row.max_uses - row.use_count),
+        bound,
+    };
+}
+/** Read a live token without spending a use. */
+async function peekEphemeral(token) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.PEEK_EPHEMERAL, [token]);
+    return rows.length ? toGrant(rows[0]) : null;
+}
+/**
+ * Spend one use of a token. A token stored with `bindOnUse` binds to `ref`
+ * on its first ref-carrying spend; after that it spends freely on that ref
+ * and never on another. Returns null when expired, exhausted, or bound
+ * elsewhere. An exhausted row stays until its TTL so a spend whose act
+ * missed can be refunded.
+ */
+async function consumeEphemeral(token, ref = null) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.CONSUME_EPHEMERAL, [token, ref]);
+    return rows.length ? toGrant(rows[0]) : null;
+}
+/** Undo one spend whose act did not land. `unbind` undoes the binding that spend made. */
+async function refundEphemeral(token, unbind) {
+    await (0, db_1.getPool)().query(sql_1.REFUND_EPHEMERAL, [token, unbind]);
+}
 /**
  * Explicitly revoke a token before expiry/exhaustion.
  */

package/build/services/iam/sql.d.ts

@@ -1,6 +1,16 @@
 /** Build INSERT for ephemeral credentials. expiresExpr is a SQL expression like 'NULL' or "NOW() + N * INTERVAL '1 second'". */
 export declare const INSERT_EPHEMERAL: (expiresExpr: string) => string;
 export declare const EXCHANGE_EPHEMERAL = "\n  UPDATE lt_ephemeral_credentials\n  SET use_count = use_count + 1\n  WHERE token = $1\n    AND (expires_at IS NULL OR expires_at > NOW())\n    AND (max_uses = 0 OR use_count < max_uses)\n  RETURNING value, use_count, max_uses";
+/** Validity check without spending a use. A bound grant stays live until its TTL. */
+export declare const PEEK_EPHEMERAL = "\n  SELECT value, use_count, max_uses, bound_ref\n  FROM lt_ephemeral_credentials\n  WHERE token = $1\n    AND (expires_at IS NULL OR expires_at > NOW())\n    AND (bound_ref IS NOT NULL OR max_uses = 0 OR use_count < max_uses)";
+/**
+ * Spend one use, binding a bind_on_use grant to $2 on its first spend.
+ * A bound grant acts again on its own ref without counting, and never on
+ * another ref. Without a ref ($2 NULL) the grant counts like any other.
+ */
+export declare const CONSUME_EPHEMERAL = "\n  UPDATE lt_ephemeral_credentials\n  SET use_count = CASE WHEN bound_ref IS NOT NULL THEN use_count ELSE use_count + 1 END,\n      bound_ref = CASE WHEN bind_on_use AND bound_ref IS NULL THEN $2::text ELSE bound_ref END\n  WHERE token = $1\n    AND (expires_at IS NULL OR expires_at > NOW())\n    AND (\n      (bound_ref IS NOT NULL AND bound_ref = $2::text)\n      OR (bound_ref IS NULL AND (max_uses = 0 OR use_count < max_uses))\n    )\n  RETURNING value, use_count, max_uses, bound_ref";
+/** Return a use an act spent but did not land; $2 also undoes the binding that spend made. */
+export declare const REFUND_EPHEMERAL = "\n  UPDATE lt_ephemeral_credentials\n  SET use_count = GREATEST(use_count - 1, 0),\n      bound_ref = CASE WHEN $2::boolean THEN NULL ELSE bound_ref END\n  WHERE token = $1";
 export declare const DELETE_EPHEMERAL = "\n  DELETE FROM lt_ephemeral_credentials WHERE token = $1";
 export declare const CLEANUP_EXPIRED_EPHEMERAL = "\n  DELETE FROM lt_ephemeral_credentials\n  WHERE expires_at IS NOT NULL AND expires_at < NOW()";
 export declare const LIST_BOTS = "\n  SELECT * FROM lt_users\n  WHERE account_type = 'bot'\n    AND ($3::text IS NULL OR status = $3)\n    AND ($4::text IS NULL\n      OR display_name ILIKE '%' || $4 || '%'\n      OR external_id ILIKE '%' || $4 || '%'\n      OR metadata->>'description' ILIKE '%' || $4 || '%')\n  ORDER BY created_at DESC\n  LIMIT $1 OFFSET $2";

package/build/services/iam/sql.js

@@ -1,11 +1,11 @@
 "use strict";
 // ─── Ephemeral credentials ──────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET_USER_WITH_ROLES_FLEXIBLE = exports.GET_USER_BY_EXTERNAL_ID = exports.SET_ACCOUNT_TYPE_BOT = exports.COUNT_BOTS = exports.LIST_BOTS = exports.CLEANUP_EXPIRED_EPHEMERAL = exports.DELETE_EPHEMERAL = exports.EXCHANGE_EPHEMERAL = exports.INSERT_EPHEMERAL = void 0;
+exports.GET_USER_WITH_ROLES_FLEXIBLE = exports.GET_USER_BY_EXTERNAL_ID = exports.SET_ACCOUNT_TYPE_BOT = exports.COUNT_BOTS = exports.LIST_BOTS = exports.CLEANUP_EXPIRED_EPHEMERAL = exports.DELETE_EPHEMERAL = exports.REFUND_EPHEMERAL = exports.CONSUME_EPHEMERAL = exports.PEEK_EPHEMERAL = exports.EXCHANGE_EPHEMERAL = exports.INSERT_EPHEMERAL = void 0;
 /** Build INSERT for ephemeral credentials. expiresExpr is a SQL expression like 'NULL' or "NOW() + N * INTERVAL '1 second'". */
 const INSERT_EPHEMERAL = (expiresExpr) => `
-  INSERT INTO lt_ephemeral_credentials (value, label, max_uses, expires_at)
-  VALUES ($1, $2, $3, ${expiresExpr})
+  INSERT INTO lt_ephemeral_credentials (value, label, max_uses, bind_on_use, expires_at)
+  VALUES ($1, $2, $3, $4, ${expiresExpr})
   RETURNING token`;
 exports.INSERT_EPHEMERAL = INSERT_EPHEMERAL;
 exports.EXCHANGE_EPHEMERAL = `
@@ -15,6 +15,35 @@ exports.EXCHANGE_EPHEMERAL = `
     AND (expires_at IS NULL OR expires_at > NOW())
     AND (max_uses = 0 OR use_count < max_uses)
   RETURNING value, use_count, max_uses`;
+/** Validity check without spending a use. A bound grant stays live until its TTL. */
+exports.PEEK_EPHEMERAL = `
+  SELECT value, use_count, max_uses, bound_ref
+  FROM lt_ephemeral_credentials
+  WHERE token = $1
+    AND (expires_at IS NULL OR expires_at > NOW())
+    AND (bound_ref IS NOT NULL OR max_uses = 0 OR use_count < max_uses)`;
+/**
+ * Spend one use, binding a bind_on_use grant to $2 on its first spend.
+ * A bound grant acts again on its own ref without counting, and never on
+ * another ref. Without a ref ($2 NULL) the grant counts like any other.
+ */
+exports.CONSUME_EPHEMERAL = `
+  UPDATE lt_ephemeral_credentials
+  SET use_count = CASE WHEN bound_ref IS NOT NULL THEN use_count ELSE use_count + 1 END,
+      bound_ref = CASE WHEN bind_on_use AND bound_ref IS NULL THEN $2::text ELSE bound_ref END
+  WHERE token = $1
+    AND (expires_at IS NULL OR expires_at > NOW())
+    AND (
+      (bound_ref IS NOT NULL AND bound_ref = $2::text)
+      OR (bound_ref IS NULL AND (max_uses = 0 OR use_count < max_uses))
+    )
+  RETURNING value, use_count, max_uses, bound_ref`;
+/** Return a use an act spent but did not land; $2 also undoes the binding that spend made. */
+exports.REFUND_EPHEMERAL = `
+  UPDATE lt_ephemeral_credentials
+  SET use_count = GREATEST(use_count - 1, 0),
+      bound_ref = CASE WHEN $2::boolean THEN NULL ELSE bound_ref END
+  WHERE token = $1`;
 exports.DELETE_EPHEMERAL = `
   DELETE FROM lt_ephemeral_credentials WHERE token = $1`;
 exports.CLEANUP_EXPIRED_EPHEMERAL = `

package/build/services/knowledge/lookup-cache.d.ts

@@ -1,4 +1,4 @@
-import type { EscalationLookupRef } from '../../types/escalation';
+import { type EscalationLookupRef } from '../../types/escalation';
 interface KnowledgeSnapshot {
     data: Record<string, unknown>;
     tags: string[];
@@ -6,24 +6,36 @@ interface KnowledgeSnapshot {
 export interface ResolvedLookup {
     domain: string;
     key: string;
-    version: number;
+    /** The edition served; null when a current ref found no edition. */
+    version: number | null;
+    /** The ref follows the newest edition rather than pinning one. */
+    current?: true;
     as?: string;
     data: Record<string, unknown> | null;
     missing?: boolean;
 }
 /** The immutable snapshot at (domain, key, version), or null when absent. */
 export declare function getKnowledgeSnapshot(domain: string, key: string, version: number): Promise<KnowledgeSnapshot | null>;
+/**
+ * The edition a ref names: its pin, or for a current ref the newest edition
+ * (the newest at `asOf` when given, so a closed row reads what was current
+ * when it closed). Null when there is none.
+ */
+export declare function resolveRefEdition(ref: EscalationLookupRef, asOf?: string | null): Promise<{
+    version: number;
+    snapshot: KnowledgeSnapshot;
+} | null>;
 /**
  * Resolve a metadata `lookups` array into the form-context `lookup` domain:
  * { [as ?? key]: data }. Returns null when there is nothing to resolve, so
  * escalations without refs cost zero SQL. Missing snapshots are omitted —
  * interpolated selects then fail closed rather than render the wrong list.
  */
-export declare function resolveLookupContext(refs: unknown): Promise<Record<string, unknown> | null>;
+export declare function resolveLookupContext(refs: unknown, asOf?: string | null): Promise<Record<string, unknown> | null>;
 /**
  * Full per-ref resolution for the lookups endpoint: every ref answers, with
  * `missing: true` marking a pin that has no snapshot — fail-visible per ref
  * without failing the batch.
  */
-export declare function resolveLookupRefs(refs: EscalationLookupRef[]): Promise<ResolvedLookup[]>;
+export declare function resolveLookupRefs(refs: EscalationLookupRef[], asOf?: string | null): Promise<ResolvedLookup[]>;
 export {};