@sequenceholdings/managed-functions 0.4.1 → 0.4.2

package/dist/monitoring-events.d.ts

@@ -0,0 +1,257 @@
+import { z } from 'zod';
+export declare const MAX_CONTEXT_TEXT_CHARS = 50000;
+export declare const MAX_SCALAR_STRING_CHARS = 8000;
+export declare const MAX_CONTEXT_JSON_CHARS = 100000;
+export declare const PRODUCER_EVENT_KEY_PREFIX = "producer:";
+export declare const artifactDeltaContextSchema: z.ZodObject<{
+    artifactKind: z.ZodString;
+    sectionPath: z.ZodString;
+    before: z.ZodString;
+    after: z.ZodString;
+    changeKind: z.ZodEnum<{
+        added: "added";
+        removed: "removed";
+        modified: "modified";
+    }>;
+    category: z.ZodOptional<z.ZodString>;
+    sourceRefs: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    workflowId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const dtiDeltaContextSchema: z.ZodObject<{
+    stageId: z.ZodString;
+    loanId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fieldPath: z.ZodString;
+    before: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    after: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    section: z.ZodOptional<z.ZodEnum<{
+        debt: "debt";
+        income: "income";
+        other: "other";
+    }>>;
+    itemLabel: z.ZodOptional<z.ZodString>;
+    calculatorType: z.ZodOptional<z.ZodEnum<{
+        basic: "basic";
+        advanced: "advanced";
+    }>>;
+    workflowId: z.ZodOptional<z.ZodString>;
+    sourceDocRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const docExtractEditContextSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    docType: z.ZodString;
+    fieldPath: z.ZodString;
+    oldValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    newValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    rowKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    stageId: z.ZodOptional<z.ZodString>;
+    workflowId: z.ZodOptional<z.ZodString>;
+    citation: z.ZodOptional<z.ZodObject<{
+        page: z.ZodNumber;
+        region: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const deltaEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    contextType: z.ZodLiteral<"artifact_delta">;
+    context: z.ZodObject<{
+        artifactKind: z.ZodString;
+        sectionPath: z.ZodString;
+        before: z.ZodString;
+        after: z.ZodString;
+        changeKind: z.ZodEnum<{
+            added: "added";
+            removed: "removed";
+            modified: "modified";
+        }>;
+        category: z.ZodOptional<z.ZodString>;
+        sourceRefs: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        workflowId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    idempotencyKey: z.ZodString;
+    subjectId: z.ZodString;
+    subjectKind: z.ZodEnum<{
+        workflow: "workflow";
+        agent: "agent";
+    }>;
+    occurredAt: z.ZodString;
+    deltaReason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deltaSource: z.ZodDefault<z.ZodEnum<{
+        unknown: "unknown";
+        human: "human";
+        llm: "llm";
+    }>>;
+    actionability: z.ZodDefault<z.ZodLiteral<"unknown">>;
+}, z.core.$strict>, z.ZodObject<{
+    contextType: z.ZodLiteral<"dti_delta">;
+    context: z.ZodObject<{
+        stageId: z.ZodString;
+        loanId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fieldPath: z.ZodString;
+        before: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        after: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        section: z.ZodOptional<z.ZodEnum<{
+            debt: "debt";
+            income: "income";
+            other: "other";
+        }>>;
+        itemLabel: z.ZodOptional<z.ZodString>;
+        calculatorType: z.ZodOptional<z.ZodEnum<{
+            basic: "basic";
+            advanced: "advanced";
+        }>>;
+        workflowId: z.ZodOptional<z.ZodString>;
+        sourceDocRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    idempotencyKey: z.ZodString;
+    subjectId: z.ZodString;
+    subjectKind: z.ZodEnum<{
+        workflow: "workflow";
+        agent: "agent";
+    }>;
+    occurredAt: z.ZodString;
+    deltaReason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deltaSource: z.ZodDefault<z.ZodEnum<{
+        unknown: "unknown";
+        human: "human";
+        llm: "llm";
+    }>>;
+    actionability: z.ZodDefault<z.ZodLiteral<"unknown">>;
+}, z.core.$strict>, z.ZodObject<{
+    contextType: z.ZodLiteral<"doc_extract_edit">;
+    context: z.ZodObject<{
+        documentId: z.ZodString;
+        docType: z.ZodString;
+        fieldPath: z.ZodString;
+        oldValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        newValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        rowKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        stageId: z.ZodOptional<z.ZodString>;
+        workflowId: z.ZodOptional<z.ZodString>;
+        citation: z.ZodOptional<z.ZodObject<{
+            page: z.ZodNumber;
+            region: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    idempotencyKey: z.ZodString;
+    subjectId: z.ZodString;
+    subjectKind: z.ZodEnum<{
+        workflow: "workflow";
+        agent: "agent";
+    }>;
+    occurredAt: z.ZodString;
+    deltaReason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deltaSource: z.ZodDefault<z.ZodEnum<{
+        unknown: "unknown";
+        human: "human";
+        llm: "llm";
+    }>>;
+    actionability: z.ZodDefault<z.ZodLiteral<"unknown">>;
+}, z.core.$strict>], "contextType">;
+export type DeltaEventInput = z.infer<typeof deltaEventSchema>;
+export type ArtifactDeltaContext = z.infer<typeof artifactDeltaContextSchema>;
+export type DtiDeltaContext = z.infer<typeof dtiDeltaContextSchema>;
+export type DocExtractEditContext = z.infer<typeof docExtractEditContextSchema>;
+export declare const MAX_DELTA_EVENTS_PER_REQUEST = 100;
+export declare const emitDeltaEventsBodySchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        contextType: z.ZodLiteral<"artifact_delta">;
+        context: z.ZodObject<{
+            artifactKind: z.ZodString;
+            sectionPath: z.ZodString;
+            before: z.ZodString;
+            after: z.ZodString;
+            changeKind: z.ZodEnum<{
+                added: "added";
+                removed: "removed";
+                modified: "modified";
+            }>;
+            category: z.ZodOptional<z.ZodString>;
+            sourceRefs: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            workflowId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        idempotencyKey: z.ZodString;
+        subjectId: z.ZodString;
+        subjectKind: z.ZodEnum<{
+            workflow: "workflow";
+            agent: "agent";
+        }>;
+        occurredAt: z.ZodString;
+        deltaReason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        deltaSource: z.ZodDefault<z.ZodEnum<{
+            unknown: "unknown";
+            human: "human";
+            llm: "llm";
+        }>>;
+        actionability: z.ZodDefault<z.ZodLiteral<"unknown">>;
+    }, z.core.$strict>, z.ZodObject<{
+        contextType: z.ZodLiteral<"dti_delta">;
+        context: z.ZodObject<{
+            stageId: z.ZodString;
+            loanId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            fieldPath: z.ZodString;
+            before: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            after: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            section: z.ZodOptional<z.ZodEnum<{
+                debt: "debt";
+                income: "income";
+                other: "other";
+            }>>;
+            itemLabel: z.ZodOptional<z.ZodString>;
+            calculatorType: z.ZodOptional<z.ZodEnum<{
+                basic: "basic";
+                advanced: "advanced";
+            }>>;
+            workflowId: z.ZodOptional<z.ZodString>;
+            sourceDocRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        idempotencyKey: z.ZodString;
+        subjectId: z.ZodString;
+        subjectKind: z.ZodEnum<{
+            workflow: "workflow";
+            agent: "agent";
+        }>;
+        occurredAt: z.ZodString;
+        deltaReason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        deltaSource: z.ZodDefault<z.ZodEnum<{
+            unknown: "unknown";
+            human: "human";
+            llm: "llm";
+        }>>;
+        actionability: z.ZodDefault<z.ZodLiteral<"unknown">>;
+    }, z.core.$strict>, z.ZodObject<{
+        contextType: z.ZodLiteral<"doc_extract_edit">;
+        context: z.ZodObject<{
+            documentId: z.ZodString;
+            docType: z.ZodString;
+            fieldPath: z.ZodString;
+            oldValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            newValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            rowKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+            stageId: z.ZodOptional<z.ZodString>;
+            workflowId: z.ZodOptional<z.ZodString>;
+            citation: z.ZodOptional<z.ZodObject<{
+                page: z.ZodNumber;
+                region: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        idempotencyKey: z.ZodString;
+        subjectId: z.ZodString;
+        subjectKind: z.ZodEnum<{
+            workflow: "workflow";
+            agent: "agent";
+        }>;
+        occurredAt: z.ZodString;
+        deltaReason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        deltaSource: z.ZodDefault<z.ZodEnum<{
+            unknown: "unknown";
+            human: "human";
+            llm: "llm";
+        }>>;
+        actionability: z.ZodDefault<z.ZodLiteral<"unknown">>;
+    }, z.core.$strict>], "contextType">>;
+}, z.core.$strict>;
+export type EmitDeltaEventsBody = z.infer<typeof emitDeltaEventsBodySchema>;
+export declare function contentHashKey(parts: ReadonlyArray<string | number>): string;
+export declare function scopedIdempotencyKey(args: {
+    scope: string;
+    parts: ReadonlyArray<string | number>;
+}): string;

package/dist/monitoring-events.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitDeltaEventsBodySchema = exports.MAX_DELTA_EVENTS_PER_REQUEST = exports.deltaEventSchema = exports.docExtractEditContextSchema = exports.dtiDeltaContextSchema = exports.artifactDeltaContextSchema = exports.PRODUCER_EVENT_KEY_PREFIX = exports.MAX_CONTEXT_JSON_CHARS = exports.MAX_SCALAR_STRING_CHARS = exports.MAX_CONTEXT_TEXT_CHARS = void 0;
+exports.contentHashKey = contentHashKey;
+exports.scopedIdempotencyKey = scopedIdempotencyKey;
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+exports.MAX_CONTEXT_TEXT_CHARS = 50_000;
+exports.MAX_SCALAR_STRING_CHARS = 8_000;
+exports.MAX_CONTEXT_JSON_CHARS = 100_000;
+exports.PRODUCER_EVENT_KEY_PREFIX = 'producer:';
+const scalarSchema = zod_1.z.union([
+    zod_1.z.string().max(exports.MAX_SCALAR_STRING_CHARS),
+    zod_1.z.number(),
+    zod_1.z.boolean(),
+    zod_1.z.null(),
+]);
+const boundedText = zod_1.z.string().max(exports.MAX_CONTEXT_TEXT_CHARS);
+const boundedId = zod_1.z.string().min(1).max(512);
+function assertBoundedContextJson(context, ctx, path = ['context']) {
+    if (JSON.stringify(context).length > exports.MAX_CONTEXT_JSON_CHARS) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: [...path],
+            message: `context JSON exceeds ${exports.MAX_CONTEXT_JSON_CHARS} characters`,
+        });
+    }
+}
+exports.artifactDeltaContextSchema = zod_1.z
+    .object({
+    artifactKind: boundedId,
+    sectionPath: boundedId,
+    before: boundedText,
+    after: boundedText,
+    changeKind: zod_1.z.enum(['added', 'removed', 'modified']),
+    category: boundedId.optional(),
+    sourceRefs: zod_1.z.record(zod_1.z.string().max(128), zod_1.z.union([zod_1.z.string().max(exports.MAX_SCALAR_STRING_CHARS), zod_1.z.number()])),
+    workflowId: boundedId.optional(),
+})
+    .strict()
+    .superRefine((context, ctx) => assertBoundedContextJson(context, ctx, []));
+exports.dtiDeltaContextSchema = zod_1.z
+    .object({
+    stageId: boundedId,
+    loanId: zod_1.z.string().max(512).nullable().optional(),
+    fieldPath: boundedId,
+    before: scalarSchema,
+    after: scalarSchema,
+    section: zod_1.z.enum(['debt', 'income', 'other']).optional(),
+    itemLabel: zod_1.z.string().max(exports.MAX_SCALAR_STRING_CHARS).optional(),
+    calculatorType: zod_1.z.enum(['basic', 'advanced']).optional(),
+    workflowId: boundedId.optional(),
+    sourceDocRefs: zod_1.z.array(zod_1.z.string().max(512)).max(50).optional(),
+})
+    .strict()
+    .superRefine((context, ctx) => assertBoundedContextJson(context, ctx, []));
+exports.docExtractEditContextSchema = zod_1.z
+    .object({
+    documentId: boundedId,
+    docType: boundedId,
+    fieldPath: boundedId,
+    oldValue: scalarSchema,
+    newValue: scalarSchema,
+    rowKey: zod_1.z.record(zod_1.z.string().max(128), scalarSchema).optional(),
+    stageId: zod_1.z.string().max(512).optional(),
+    workflowId: zod_1.z.string().max(512).optional(),
+    citation: zod_1.z
+        .object({
+        page: zod_1.z.number().int(),
+        region: zod_1.z.string().max(exports.MAX_SCALAR_STRING_CHARS).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .superRefine((context, ctx) => assertBoundedContextJson(context, ctx, []));
+const deltaEventBaseFields = {
+    idempotencyKey: zod_1.z.string().min(1).max(512),
+    subjectId: zod_1.z.string().min(1).max(512),
+    subjectKind: zod_1.z.enum(['agent', 'workflow']),
+    occurredAt: zod_1.z.string().datetime({ offset: true }),
+    deltaReason: zod_1.z.string().max(exports.MAX_CONTEXT_TEXT_CHARS).nullable().optional(),
+    deltaSource: zod_1.z.enum(['human', 'llm', 'unknown']).default('unknown'),
+    actionability: zod_1.z.literal('unknown').default('unknown'),
+};
+exports.deltaEventSchema = zod_1.z.discriminatedUnion('contextType', [
+    zod_1.z
+        .object({
+        ...deltaEventBaseFields,
+        contextType: zod_1.z.literal('artifact_delta'),
+        context: exports.artifactDeltaContextSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...deltaEventBaseFields,
+        contextType: zod_1.z.literal('dti_delta'),
+        context: exports.dtiDeltaContextSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...deltaEventBaseFields,
+        contextType: zod_1.z.literal('doc_extract_edit'),
+        context: exports.docExtractEditContextSchema,
+    })
+        .strict(),
+]);
+exports.MAX_DELTA_EVENTS_PER_REQUEST = 100;
+exports.emitDeltaEventsBodySchema = zod_1.z
+    .object({
+    events: zod_1.z.array(exports.deltaEventSchema).min(1).max(exports.MAX_DELTA_EVENTS_PER_REQUEST),
+})
+    .strict()
+    .superRefine((body, ctx) => {
+    const seen = new Set();
+    body.events.forEach((event, index) => {
+        if (event.idempotencyKey.startsWith(exports.PRODUCER_EVENT_KEY_PREFIX)) {
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ['events', index, 'idempotencyKey'], message: 'Producer event storage keys are reserved for scoped monitoring delivery' });
+        }
+        if (seen.has(event.idempotencyKey)) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: ['events', index, 'idempotencyKey'],
+                message: `Duplicate idempotencyKey in batch: ${event.idempotencyKey}`,
+            });
+        }
+        seen.add(event.idempotencyKey);
+    });
+});
+function contentHashKey(parts) {
+    return (0, node_crypto_1.createHash)('sha256').update(parts.join('|')).digest('hex').slice(0, 16);
+}
+function scopedIdempotencyKey(args) {
+    return `${args.scope}:${contentHashKey(args.parts)}`;
+}

package/dist/monitoring.d.ts

@@ -0,0 +1,14 @@
+import { type MonitoringCatalogQuery, type MonitoringBucketCatalog, type MonitoringDeliveryKey, type MonitoringDeliveryReceipt, type MonitoringPublish } from './monitoring-contract';
+export interface FunctionServiceMonitoringOptions {
+    request: {
+        headers: Pick<Headers, 'get'> | Readonly<Record<string, string | readonly string[] | undefined>>;
+    };
+    baseUrl: string;
+    fetchImpl?: typeof globalThis.fetch;
+}
+export interface FunctionServiceMonitoringClient {
+    publish(input: MonitoringPublish): Promise<MonitoringDeliveryReceipt>;
+    get(input: MonitoringDeliveryKey): Promise<MonitoringDeliveryReceipt>;
+    getBucketCatalog(input: MonitoringCatalogQuery): Promise<MonitoringBucketCatalog>;
+}
+export declare function createFunctionServiceMonitoringClient({ request, baseUrl, fetchImpl }: FunctionServiceMonitoringOptions): FunctionServiceMonitoringClient;

package/dist/monitoring.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFunctionServiceMonitoringClient = createFunctionServiceMonitoringClient;
+const zod_1 = require("zod");
+const monitoring_contract_1 = require("./monitoring-contract");
+function credential(request) {
+    const headers = request.headers;
+    const matches = typeof headers.get === 'function'
+        ? [headers.get(monitoring_contract_1.FUNCTION_MONITORING_TOKEN_HEADER)]
+        : Object.entries(headers).filter(([name]) => name.toLowerCase() === monitoring_contract_1.FUNCTION_MONITORING_TOKEN_HEADER).map(([, value]) => value);
+    const token = matches[0];
+    const invalid = () => new monitoring_contract_1.FunctionMonitoringError(401, 'invalid_context', 'This invocation has no valid monitoring credential');
+    if (matches.length !== 1 || typeof token !== 'string' || token.length > 16_384)
+        throw invalid();
+    const envelope = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{43})$/.exec(token);
+    if (!envelope?.[1])
+        throw invalid();
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(envelope[1], 'base64url').toString('utf8'));
+    }
+    catch {
+        throw invalid();
+    }
+    const parsed = zod_1.z.object({ audience: zod_1.z.literal('atlas-managed-function-monitoring'), sub: zod_1.z.string().startsWith('service-account|'), exp: zod_1.z.number().int() }).safeParse(value);
+    if (!parsed.success)
+        throw invalid();
+    return { token, expiresAt: parsed.data.exp };
+}
+function origin(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new monitoring_contract_1.FunctionMonitoringError(400, 'invalid_configuration', 'Configure a trusted Atlas origin');
+    }
+    const local = url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if ((!local && url.protocol !== 'https:') || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+        throw new monitoring_contract_1.FunctionMonitoringError(400, 'invalid_configuration', 'Configure an HTTPS Atlas origin without credentials, path, query or fragment');
+    }
+    return url.origin;
+}
+function createFunctionServiceMonitoringClient({ request, baseUrl, fetchImpl = globalThis.fetch }) {
+    const url = `${origin(baseUrl)}${monitoring_contract_1.FUNCTION_MONITORING_DELIVERIES_PATH}`;
+    const { token, expiresAt } = credential(request);
+    async function call(body) {
+        if (expiresAt <= Date.now() / 1000)
+            throw new monitoring_contract_1.FunctionMonitoringError(401, 'expired_context', 'The monitoring credential expired; start a new invocation');
+        const input = monitoring_contract_1.functionMonitoringRequestSchema.parse(body);
+        const response = await fetchImpl(url, {
+            method: 'POST', headers: { 'content-type': 'application/json', [monitoring_contract_1.FUNCTION_MONITORING_TOKEN_HEADER]: token },
+            body: JSON.stringify(input), redirect: 'error', signal: AbortSignal.timeout(30_000),
+        });
+        const result = await response.json().catch(() => null);
+        if (!response.ok) {
+            const error = zod_1.z.object({ code: zod_1.z.string().max(128).optional(), detail: zod_1.z.string().max(2000).optional() }).safeParse(result);
+            throw new monitoring_contract_1.FunctionMonitoringError(response.status, error.success ? (error.data.code ?? 'monitoring_failed') : 'monitoring_failed', error.success ? (error.data.detail ?? 'Monitoring delivery failed') : 'Monitoring delivery failed');
+        }
+        return result;
+    }
+    async function delivery(input, operation) {
+        const validated = monitoring_contract_1.monitoringDeliveryReceiptSchema.safeParse(await call({ ...input, operation }));
+        if (!validated.success || validated.data.producer !== input.producer || validated.data.businessKey !== input.businessKey || ('payloadHash' in input && validated.data.payloadHash !== input.payloadHash) || ('events' in input && validated.data.eventCount !== input.events.length)) {
+            throw new monitoring_contract_1.FunctionMonitoringError(502, 'malformed_response', 'Atlas returned an invalid monitoring receipt');
+        }
+        return validated.data;
+    }
+    return {
+        publish: input => delivery(input, 'publish'), get: input => delivery(input, 'get'),
+        async getBucketCatalog(input) {
+            const validated = monitoring_contract_1.monitoringBucketCatalogSchema.safeParse(await call({ ...input, operation: 'getBucketCatalog' }));
+            if (!validated.success || validated.data.producer !== input.producer)
+                throw new monitoring_contract_1.FunctionMonitoringError(502, 'malformed_response', 'Atlas returned an invalid monitoring catalog');
+            return validated.data;
+        },
+    };
+}

package/dist/orm-contract.d.ts

@@ -0,0 +1 @@
+export declare const FUNCTION_CALLER_DATA_TOKEN_HEADER = "x-sequence-caller-data-token";

package/dist/orm-contract.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FUNCTION_CALLER_DATA_TOKEN_HEADER = void 0;
+exports.FUNCTION_CALLER_DATA_TOKEN_HEADER = 'x-sequence-caller-data-token';

package/dist/orm.d.ts

@@ -56,6 +56,8 @@ interface OperationsManifest {
 interface OperationExecutionOptions {
     /** Reuse only when retrying the same logical mutation. */
     idempotencyKey?: string;
+    /** Require the same source publication as an earlier read receipt. */
+    expectedSourceGeneration?: string;
 }
 interface OperationExecutor {
     /** Execute a manifest operation by name (or a raw `sha256:` hash). */
@@ -66,6 +68,19 @@ interface SqlOperationExecutor extends OperationExecutor {
     /** Default read-only ontology SQL; no authored operation or manifest needed. */
     sql(variables: SqlQueryVariables): Promise<SqlQueryResult>;
 }
+interface OperationReadReceipt<TData> {
+    readonly data: TData;
+    /** Opaque source-publication identity; never an authorization credential. */
+    readonly sourceGeneration: string;
+}
+interface ReadReceiptOperationExecutor extends OperationExecutor {
+    /** Execute a registered query or built-in SQL read; fail closed without a receipt. */
+    executeWithReadReceipt<TData = Record<string, unknown>>(op: string, variables?: Record<string, unknown>, options?: OperationExecutionOptions): Promise<OperationReadReceipt<TData>>;
+}
+/** Additive factories preserve existing host wrappers without receipt support. */
+type ReadReceiptSqlOperationExecutor = SqlOperationExecutor & ReadReceiptOperationExecutor;
+
+declare const FUNCTION_CALLER_DATA_TOKEN_HEADER = "x-sequence-caller-data-token";
 
 type FunctionOrmErrorCode = 'INVALID_CONFIGURATION' | 'MISSING_CALLER_CONTEXT' | 'INVALID_CALLER_CONTEXT' | 'UNSUPPORTED_CALLER' | 'EXPIRED_CALLER_CONTEXT';
 declare class FunctionOrmError extends Error {
@@ -87,7 +102,8 @@ interface FunctionOrmExecutorOptions {
     fetchImpl?: typeof globalThis.fetch;
     jsonScalars?: FunctionOrmJsonScalars;
 }
-declare function createFunctionOrmExecutor({ request, fetchImpl, ...options }: FunctionOrmExecutorOptions): SqlOperationExecutor;
-declare function createFunctionServiceOrmExecutor({ request, fetchImpl, ...options }: FunctionOrmExecutorOptions): SqlOperationExecutor;
+declare function createFunctionOrmExecutor({ request, fetchImpl, ...options }: FunctionOrmExecutorOptions): ReadReceiptSqlOperationExecutor;
+declare function createFunctionCallerOrmExecutor({ request, fetchImpl, ...options }: FunctionOrmExecutorOptions): ReadReceiptSqlOperationExecutor;
+declare function createFunctionServiceOrmExecutor({ request, fetchImpl, ...options }: FunctionOrmExecutorOptions): ReadReceiptSqlOperationExecutor;
 
-export { FunctionOrmError, type FunctionOrmErrorCode, type FunctionOrmExecutorOptions, type FunctionOrmJsonScalars, type FunctionOrmRequest, ORM_JSON_SCALARS_HEADER, ORM_LOSSLESS_JSON_SCALARS, type OperationExecutor, type OperationsManifest, OrmClientError, OrmOperationError, type SqlOperationExecutor, createFunctionOrmExecutor, createFunctionServiceOrmExecutor };
+export { FUNCTION_CALLER_DATA_TOKEN_HEADER, FunctionOrmError, type FunctionOrmErrorCode, type FunctionOrmExecutorOptions, type FunctionOrmJsonScalars, type FunctionOrmRequest, ORM_JSON_SCALARS_HEADER, ORM_LOSSLESS_JSON_SCALARS, type OperationExecutor, type OperationReadReceipt, type OperationsManifest, OrmClientError, OrmOperationError, type ReadReceiptSqlOperationExecutor, type SqlOperationExecutor, createFunctionCallerOrmExecutor, createFunctionOrmExecutor, createFunctionServiceOrmExecutor };