slotlock 0.6.2 → 0.7.0

package/otel.d.ts

@@ -0,0 +1,86 @@
+import type { SlotlockAgentServerEvent } from './agent-server.js';
+import type { SlotlockMetrics } from './metrics.js';
+export interface SlotlockOtlpConfig {
+    /** Where spans are POSTed: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, or OTEL_EXPORTER_OTLP_ENDPOINT + /v1/traces. */
+    tracesUrl: string;
+    /** Sent with each export (OTEL_EXPORTER_OTLP_HEADERS), such as a collector's API key. */
+    headers: Readonly<Record<string, string>>;
+    /** service.name (OTEL_SERVICE_NAME), `slotlock` by default. */
+    serviceName: string;
+    /**
+     * Where metrics are POSTed: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, or OTEL_EXPORTER_OTLP_ENDPOINT +
+     * /v1/metrics; none with only a traces endpoint.
+     */
+    metricsUrl?: string;
+}
+export interface SlotlockTraceExporter {
+    /** Turn an agent server event into a span, if it is a call; a child of `parentSpanId` when given. */
+    record(event: SlotlockAgentServerEvent, parentSpanId?: string): void;
+    /** Send what is queued now. */
+    flush(): Promise<void>;
+    /** Stop the timer and send what is left. */
+    shutdown(): Promise<void>;
+    /** Spans dropped because the queue was full or the collector refused or did not answer. */
+    readonly dropped: number;
+}
+interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: 2;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: {
+        key: string;
+        value: {
+            stringValue: string;
+        } | {
+            intValue: string;
+        };
+    }[];
+    status: {
+        code: 1 | 2;
+    };
+}
+/** The span a call event makes, or null for any other event. */
+export declare function slotlockCallSpan(event: SlotlockAgentServerEvent, endedAtMs: number, 
+/** The caller's span from its traceparent: the call's span is its child. */
+parentSpanId?: string): Span | null;
+/** Read the standard OTEL_* variables; undefined when no endpoint is set. */
+export declare function readSlotlockOtlpConfig(env: Readonly<Record<string, string | undefined>>): SlotlockOtlpConfig | undefined;
+/** Batch spans to an OTLP/HTTP collector as JSON. */
+export declare function createSlotlockOtlpExporter(config: SlotlockOtlpConfig, 
+/**
+ * The service's version is not sent: the deployed one is on /healthz and /metrics, and an export
+ * carries nothing read from a file.
+ */
+options: {
+    fetch?: typeof fetch;
+    now?: () => number;
+    intervalMs?: number;
+    maxBatch?: number;
+    maxQueue?: number;
+    timeoutMs?: number;
+    /** Told when an export fails: its HTTP status, or that the collector did not answer. Never a header. */
+    onError?: (reason: string) => void;
+}): SlotlockTraceExporter;
+/** The snapshot of a server's metrics as an OTLP/HTTP JSON body: cumulative sums, histograms, gauges. */
+export declare function slotlockOtlpMetricsBody(metrics: ReturnType<SlotlockMetrics['collect']>, serviceName: string, nowMs: number): string;
+/**
+ * Send a server's metrics to an OTLP/HTTP collector every `intervalMs` (60 seconds), cumulative
+ * since the server started, as the scrape at /metrics counts them; a collector that is down costs
+ * that export, never a request.
+ */
+export declare function createSlotlockOtlpMetricsExporter(config: SlotlockOtlpConfig & {
+    metricsUrl: string;
+}, metrics: SlotlockMetrics, options?: {
+    fetch?: typeof fetch;
+    now?: () => number;
+    intervalMs?: number;
+    onError?: (reason: string) => void;
+}): {
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+};
+export {};

package/otel.js

@@ -0,0 +1,273 @@
+// OpenTelemetry trace export for `slotlock serve` (RFC 0002 P2-5, RFC 0003 Later): one SERVER span
+// per agent and REST call, sent to an OTLP/HTTP collector as JSON (OTEL_EXPORTER_OTLP_ENDPOINT).
+// A call that carried a valid `traceparent` joins the caller's trace as a child of the caller's
+// span, which reaches the exporter through the agent server's onCallTrace alone, never its events
+// or logs.
+//
+// What a span says is what /metrics and the logs already say: the protocol, the operation, the
+// outcome or HTTP status, and how long it took. Never a tenant, a key, an argument or an address.
+// Spans wait in a bounded queue and go in batches; a collector that is down or slow costs dropped
+// spans, counted, never a request.
+import { randomBytes } from 'node:crypto';
+const HEX_TRACE = /^[0-9a-f]{32}$/;
+/** Outcomes that are the server's failure, not the caller's: the span is an error. */
+const SERVER_FAILURES = new Set(['internal_error', 'unavailable']);
+const nanos = (ms) => (BigInt(Math.round(ms * 1_000)) * 1000n).toString();
+/** The span a call event makes, or null for any other event. */
+export function slotlockCallSpan(event, endedAtMs, 
+/** The caller's span from its traceparent: the call's span is its child. */
+parentSpanId) {
+    if (event.type !== 'call' && event.type !== 'rest')
+        return null;
+    const protocol = event.type === 'rest' ? 'rest' : event.protocol;
+    const failed = event.type === 'rest' ? event.status >= 500 : SERVER_FAILURES.has(event.outcome);
+    const traceId = event.traceId !== undefined && HEX_TRACE.test(event.traceId) ? event.traceId : randomBytes(16).toString('hex');
+    const parent = event.traceId !== undefined && parentSpanId !== undefined && /^[0-9a-f]{16}$/.test(parentSpanId) && parentSpanId !== '0'.repeat(16)
+        ? parentSpanId
+        : undefined;
+    return {
+        traceId,
+        spanId: randomBytes(8).toString('hex'),
+        ...(parent ? { parentSpanId: parent } : {}),
+        name: `${protocol} ${event.operation}`,
+        kind: 2,
+        startTimeUnixNano: nanos(endedAtMs - Math.max(0, event.durationMs)),
+        endTimeUnixNano: nanos(endedAtMs),
+        attributes: [
+            { key: 'slotlock.protocol', value: { stringValue: protocol } },
+            { key: 'slotlock.operation', value: { stringValue: event.operation } },
+            event.type === 'rest'
+                ? { key: 'http.response.status_code', value: { intValue: String(event.status) } }
+                : { key: 'slotlock.outcome', value: { stringValue: event.outcome } },
+        ],
+        status: { code: failed ? 2 : 1 },
+    };
+}
+/** Read the standard OTEL_* variables; undefined when no endpoint is set. */
+export function readSlotlockOtlpConfig(env) {
+    // Each read whether or not export is on, so `slotlock --help` lists exactly what is read.
+    const traces = env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim();
+    const metrics = env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT?.trim();
+    const base = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+    const headerList = env.OTEL_EXPORTER_OTLP_HEADERS ?? '';
+    const service = env.OTEL_SERVICE_NAME?.trim();
+    if (!traces && !base && !metrics)
+        return undefined;
+    // Trailing slashes trimmed by hand: a regular expression for it backtracks on a long run of them.
+    let trimmed = base ?? '';
+    while (trimmed.endsWith('/'))
+        trimmed = trimmed.slice(0, -1);
+    const checked = (url) => {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw Object.assign(new Error('OTEL_EXPORTER_OTLP_ENDPOINT must be an http or https URL'), { code: 'invalid_otlp_endpoint' });
+        }
+        if ((parsed.protocol !== 'https:' && parsed.protocol !== 'http:') || parsed.username || parsed.password) {
+            throw Object.assign(new Error('OTEL_EXPORTER_OTLP_ENDPOINT must be an http or https URL without credentials'), {
+                code: 'invalid_otlp_endpoint',
+            });
+        }
+        return parsed.href;
+    };
+    const tracesUrl = traces ? checked(traces) : base ? checked(`${trimmed}/v1/traces`) : '';
+    const metricsUrl = metrics ? checked(metrics) : base ? checked(`${trimmed}/v1/metrics`) : undefined;
+    const headers = {};
+    for (const part of headerList.split(',')) {
+        if (part.trim() === '')
+            continue;
+        const at = part.indexOf('=');
+        const name = at > 0 ? part.slice(0, at).trim() : '';
+        let value = '';
+        try {
+            value = decodeURIComponent(part.slice(at + 1).trim());
+        }
+        catch {
+            value = '';
+        }
+        if (!/^[A-Za-z0-9-]{1,100}$/.test(name) || value === '' || /[\r\n]/.test(value)) {
+            throw Object.assign(new Error('OTEL_EXPORTER_OTLP_HEADERS must be comma-separated name=value pairs'), {
+                code: 'invalid_otlp_headers',
+            });
+        }
+        headers[name.toLowerCase()] = value;
+    }
+    const serviceName = service || 'slotlock';
+    if (!/^[\x21-\x7e]{1,100}$/.test(serviceName)) {
+        throw Object.assign(new Error('OTEL_SERVICE_NAME must be 1-100 printable characters'), { code: 'invalid_otlp_service' });
+    }
+    return { tracesUrl, headers, serviceName, ...(metricsUrl ? { metricsUrl } : {}) };
+}
+/** Batch spans to an OTLP/HTTP collector as JSON. */
+export function createSlotlockOtlpExporter(config, 
+/**
+ * The service's version is not sent: the deployed one is on /healthz and /metrics, and an export
+ * carries nothing read from a file.
+ */
+options) {
+    const send = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    const maxBatch = options.maxBatch ?? 256;
+    const maxQueue = options.maxQueue ?? 4_096;
+    const queue = [];
+    let dropped = 0;
+    let sending = Promise.resolve();
+    const resource = {
+        attributes: [
+            { key: 'service.name', value: { stringValue: config.serviceName } },
+            { key: 'telemetry.sdk.name', value: { stringValue: 'slotlock' } },
+        ],
+    };
+    async function exportBatch(spans) {
+        try {
+            const response = await send(config.tracesUrl, {
+                method: 'POST',
+                headers: { ...config.headers, 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    resourceSpans: [{ resource, scopeSpans: [{ scope: { name: 'slotlock' }, spans }] }],
+                }),
+                signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+            });
+            if (!response.ok) {
+                dropped += spans.length;
+                options.onError?.(`collector answered HTTP ${response.status}`);
+            }
+            await response.body?.cancel().catch(() => undefined);
+        }
+        catch {
+            dropped += spans.length;
+            options.onError?.('collector did not answer');
+        }
+    }
+    function flush() {
+        // One export at a time, in order.
+        sending = sending.then(async () => {
+            while (queue.length > 0)
+                await exportBatch(queue.splice(0, maxBatch));
+        });
+        return sending;
+    }
+    const timer = setInterval(() => void flush(), options.intervalMs ?? 5_000);
+    timer.unref?.();
+    return {
+        record(event, parentSpanId) {
+            const span = slotlockCallSpan(event, now(), parentSpanId);
+            if (!span)
+                return;
+            if (queue.length >= maxQueue) {
+                dropped += 1;
+                return;
+            }
+            queue.push(span);
+            if (queue.length >= maxBatch)
+                void flush();
+        },
+        flush,
+        async shutdown() {
+            clearInterval(timer);
+            await flush();
+        },
+        get dropped() {
+            return dropped;
+        },
+    };
+}
+/** The snapshot of a server's metrics as an OTLP/HTTP JSON body: cumulative sums, histograms, gauges. */
+export function slotlockOtlpMetricsBody(metrics, serviceName, nowMs) {
+    const start = nanos(metrics.startedAtMs);
+    const time = nanos(nowMs);
+    const attributes = (labels) => Object.entries(labels).map(([key, value]) => ({ key, value: { stringValue: value } }));
+    return JSON.stringify({
+        resourceMetrics: [
+            {
+                resource: { attributes: [{ key: 'service.name', value: { stringValue: serviceName } }] },
+                scopeMetrics: [
+                    {
+                        scope: { name: 'slotlock' },
+                        metrics: [
+                            ...metrics.counters.map((counter) => ({
+                                name: counter.name,
+                                description: counter.help,
+                                sum: {
+                                    aggregationTemporality: 2,
+                                    isMonotonic: true,
+                                    dataPoints: counter.points.map((point) => ({
+                                        attributes: attributes(point.labels),
+                                        startTimeUnixNano: start,
+                                        timeUnixNano: time,
+                                        asDouble: point.value,
+                                    })),
+                                },
+                            })),
+                            ...metrics.histograms.map((histogram) => ({
+                                name: histogram.name,
+                                description: histogram.help,
+                                unit: 's',
+                                histogram: {
+                                    aggregationTemporality: 2,
+                                    dataPoints: histogram.points.map((point) => ({
+                                        attributes: attributes(point.labels),
+                                        startTimeUnixNano: start,
+                                        timeUnixNano: time,
+                                        count: String(point.count),
+                                        sum: point.sum,
+                                        explicitBounds: [...histogram.bounds],
+                                        // OTLP counts each bucket on its own; the scrape's are cumulative.
+                                        bucketCounts: [...point.cumulative.map((count, index) => count - (index === 0 ? 0 : (point.cumulative[index - 1] ?? 0))), point.count - (point.cumulative.at(-1) ?? 0)].map(String),
+                                    })),
+                                },
+                            })),
+                            ...metrics.gauges.map((gauge) => ({
+                                name: gauge.name,
+                                description: gauge.help,
+                                gauge: {
+                                    dataPoints: gauge.points.map((point) => ({ attributes: attributes(point.labels), timeUnixNano: time, asDouble: point.value })),
+                                },
+                            })),
+                        ],
+                    },
+                ],
+            },
+        ],
+    });
+}
+/**
+ * Send a server's metrics to an OTLP/HTTP collector every `intervalMs` (60 seconds), cumulative
+ * since the server started, as the scrape at /metrics counts them; a collector that is down costs
+ * that export, never a request.
+ */
+export function createSlotlockOtlpMetricsExporter(config, metrics, options = {}) {
+    const send = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    let sending = Promise.resolve();
+    const flush = () => {
+        sending = sending.then(async () => {
+            try {
+                const response = await send(config.metricsUrl, {
+                    method: 'POST',
+                    headers: { ...config.headers, 'content-type': 'application/json' },
+                    body: slotlockOtlpMetricsBody(metrics.collect(), config.serviceName, now()),
+                    signal: AbortSignal.timeout(10_000),
+                });
+                if (!response.ok)
+                    options.onError?.(`collector answered HTTP ${response.status}`);
+                await response.body?.cancel().catch(() => undefined);
+            }
+            catch {
+                options.onError?.('collector did not answer');
+            }
+        });
+        return sending;
+    };
+    const timer = setInterval(() => void flush(), options.intervalMs ?? 60_000);
+    timer.unref?.();
+    return {
+        flush,
+        async shutdown() {
+            clearInterval(timer);
+            await flush();
+        },
+    };
+}

package/overage.d.ts

@@ -0,0 +1,33 @@
+import type { Sql } from 'postgres';
+/** The stop percent overage moves a paying Developer tenant to unless SLOTLOCK_OVERAGE_STOP_PERCENT says. */
+export declare const SLOTLOCK_DEFAULT_OVERAGE_STOP_PERCENT = 300;
+export interface SlotlockOverageReport {
+    month: string;
+    /** Tenants with operations above their quota this month, and what each was billed now. */
+    tenants: {
+        tenant: string;
+        over: number;
+        reported: number;
+        sent: number;
+    }[];
+    /** Operations sent to Stripe in this run. */
+    sent: number;
+    /** Tenants whose event Stripe did not take (run again). */
+    failed: number;
+}
+/** `YYYY-MM` of a time, UTC. */
+export declare function slotlockMonthOf(at: number): string;
+/**
+ * Report each paying Developer tenant's operations above its quota in `month` to Stripe, once.
+ * Runs as the schema owner. A month can be reported while it runs and once more after it ends.
+ */
+export declare function reportSlotlockOverage(sql: Sql, input: {
+    month: string;
+    stripe: {
+        secretKey: string;
+        eventName: string;
+        fetch?: typeof fetch;
+        apiBase?: string;
+    };
+    now?: number;
+}): Promise<SlotlockOverageReport>;

package/overage.js

@@ -0,0 +1,115 @@
+// Metered overage for Developer (RFC 0003 "Later"), off unless SLOTLOCK_OVERAGE=on. Stripe's test
+// mode takes the metered price in a Managed Payments checkout (read 2026-11-10, RFC 0003 vendor
+// facts); it stays off until a paid test subscription shows the meter billed and the Terms say what
+// overage costs.
+//
+// With it on: a paying Developer tenant is not refused at 110% of its monthly operations but at
+// SLOTLOCK_OVERAGE_STOP_PERCENT (300% by default); checkout adds the metered price
+// (SLOTLOCK_STRIPE_PRICE_OVERAGE) to its subscription; and `slotlock overage report`, run by the
+// owner (daily, and on the 1st for the month before), sends Stripe a Billing Meter event for each
+// tenant's operations above its quota that it has not reported yet. What was reported is recorded
+// in slotlock.overage_reports first by month, so no operation is billed twice, and each event
+// carries an identifier Stripe deduplicates within a day: Stripe refusing one as already taken counts
+// as sent.
+import { createHash } from 'node:crypto';
+import { SLOTLOCK_STRIPE_API_VERSION } from './billing.js';
+import { SLOTLOCK_PLAN_QUOTAS } from './plans.js';
+/** The stop percent overage moves a paying Developer tenant to unless SLOTLOCK_OVERAGE_STOP_PERCENT says. */
+export const SLOTLOCK_DEFAULT_OVERAGE_STOP_PERCENT = 300;
+/** `YYYY-MM` of a time, UTC. */
+export function slotlockMonthOf(at) {
+    return new Date(at).toISOString().slice(0, 7);
+}
+/**
+ * Report each paying Developer tenant's operations above its quota in `month` to Stripe, once.
+ * Runs as the schema owner. A month can be reported while it runs and once more after it ends.
+ */
+export async function reportSlotlockOverage(sql, input) {
+    if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(input.month)) {
+        throw Object.assign(new Error('Slotlock month must be YYYY-MM'), { code: 'invalid_month' });
+    }
+    if (!/^[A-Za-z0-9_-]{1,100}$/.test(input.stripe.eventName)) {
+        throw Object.assign(new Error('Slotlock overage meter event name must be 1-100 of A-Z, a-z, 0-9, _ and -'), {
+            code: 'invalid_meter_event',
+        });
+    }
+    const from = `${input.month}-01`;
+    const [year, monthNumber] = input.month.split('-').map(Number);
+    // The month's last second: a closed month's events are dated in it.
+    const monthEnd = Date.UTC(year, monthNumber, 1) - 1_000;
+    const quota = SLOTLOCK_PLAN_QUOTAS.developer.operations;
+    // Paying Developer tenants (their own plan, a live subscription) and what they used this month.
+    const rows = await sql `
+    SELECT plan.tenant_ref, plan.stripe_customer AS customer,
+           COALESCE((SELECT sum(used.count) FROM slotlock.usage_daily used
+                      WHERE used.tenant_ref = plan.tenant_ref AND used.metric = 'operations'
+                        AND used.day >= ${from}::date
+                        AND used.day < (${from}::date + interval '1 month')), 0)::text AS used,
+           (SELECT done.reported FROM slotlock.overage_reports done
+             WHERE done.tenant_ref = plan.tenant_ref AND done.month = ${from}::date)::text AS reported
+      FROM slotlock.tenant_plans plan
+     WHERE plan.plan = 'developer' AND plan.source = 'direct'
+       AND plan.stripe_customer IS NOT NULL AND plan.stripe_subscription IS NOT NULL
+       AND plan.status <> 'canceled'
+     ORDER BY plan.tenant_ref`;
+    const send = input.stripe.fetch ?? fetch;
+    const report = { month: input.month, tenants: [], sent: 0, failed: 0 };
+    for (const row of rows) {
+        const over = Math.max(0, Number(row.used) - quota);
+        const reported = Number(row.reported ?? 0);
+        if (over <= reported) {
+            if (over > 0)
+                report.tenants.push({ tenant: row.tenant_ref, over, reported, sent: 0 });
+            continue;
+        }
+        const delta = over - reported;
+        // Recorded first: a run that stops between the two bills too little, never twice.
+        await sql `
+      INSERT INTO slotlock.overage_reports (tenant_ref, month, reported)
+      VALUES (${row.tenant_ref}, ${from}::date, ${over})
+      ON CONFLICT (tenant_ref, month) DO UPDATE
+        SET reported = GREATEST(slotlock.overage_reports.reported, EXCLUDED.reported), updated_at = statement_timestamp()`;
+        // The same total gives the same identifier, so a retry within Stripe's window is one event.
+        const identifier = `slotlock-overage-${createHash('sha256').update(row.tenant_ref).digest('hex').slice(0, 24)}-${input.month}-${over}`;
+        const response = await send(`${input.stripe.apiBase ?? 'https://api.stripe.com'}/v1/billing/meter_events`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${input.stripe.secretKey}`,
+                'content-type': 'application/x-www-form-urlencoded',
+                'stripe-version': SLOTLOCK_STRIPE_API_VERSION,
+            },
+            body: new URLSearchParams({
+                event_name: input.stripe.eventName,
+                identifier,
+                'payload[stripe_customer_id]': row.customer,
+                'payload[value]': String(delta),
+                // Within the month it is billed in; a closed month's are dated its last second.
+                timestamp: String(Math.floor(Math.min(input.now ?? Date.now(), monthEnd) / 1_000)),
+            }).toString(),
+        }).catch(() => null);
+        if (!response?.ok && !(await takenBefore(response, identifier))) {
+            // Not taken: put the record back, so the next run sends it.
+            await sql `
+        UPDATE slotlock.overage_reports SET reported = ${reported}, updated_at = statement_timestamp()
+         WHERE tenant_ref = ${row.tenant_ref} AND month = ${from}::date AND reported = ${over}`;
+            report.failed += 1;
+            report.tenants.push({ tenant: row.tenant_ref, over, reported, sent: 0 });
+            continue;
+        }
+        report.sent += delta;
+        report.tenants.push({ tenant: row.tenant_ref, over, reported: over, sent: delta });
+    }
+    return report;
+}
+/**
+ * Whether Stripe refused an event only because it took one with this identifier before: a run whose
+ * answer was lost sends it again, and Stripe says so with a 400 and no code (read in test mode,
+ * 2026-11-10). Counted as sent, or the record would go back and the next total bill this delta twice.
+ */
+async function takenBefore(response, identifier) {
+    if (response?.status !== 400)
+        return false;
+    const body = (await response.json().catch(() => null));
+    return (body?.error?.type === 'invalid_request_error' &&
+        body.error.message === `An event already exists with identifier ${identifier}.`);
+}

package/package-version.js

@@ -1,7 +1,5 @@
-// The package version, read from package.json so that file is the one place it is set. Built, this
-// module sits beside the artifact's own package.json (scripts/prepare-package.mjs writes it from the
-// root one), which is where it is installed from npm or copied into the image; run from a checkout's
-// src/, the root package.json is one directory up.
+// Read from package.json so that file is the one place the version is set: built, the artifact's
+// own package.json sits beside this module; in a checkout's src/, the root one is a directory up.
 import { readFileSync } from 'node:fs';
 /** Slotlock's version, or `'unknown'` where no manifest of its own can be read (a bundle). */
 export function slotlockPackageVersion() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slotlock",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "type": "module",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "license": "Apache-2.0",

package/partner-billing.d.ts

@@ -0,0 +1,81 @@
+import type { Sql } from 'postgres';
+import { type SlotlockPartnerContract } from './partners.js';
+import { type SlotlockWebhookSender } from './webhooks.js';
+/** One account's month: each metric's total (resources: the most it held on a day). */
+export interface SlotlockPartnerAccountMonth {
+    account: string;
+    plan: string;
+    totals: Readonly<Record<string, number>>;
+}
+/** One invoice line, in the contract currency's minor units. */
+export interface SlotlockPartnerInvoiceLine {
+    line: string;
+    description: string;
+    quantity: number;
+    amount: number;
+    currency: string;
+}
+/**
+ * Price a month with the contract (P6): each account with at least one operation, each 10,000
+ * operations and each 100 bookings an account made above its plan's quota (each account rounded up
+ * on its own), and the minimum's shortfall. No pricing in the contract: no lines.
+ */
+export declare function priceSlotlockPartnerMonth(contract: SlotlockPartnerContract, accounts: readonly SlotlockPartnerAccountMonth[]): SlotlockPartnerInvoiceLine[];
+/** The SHA-256 (hex) of a month's canonical rows: `account\tmetric\tcount` lines, sorted, then the invoice lines. */
+export declare function slotlockPartnerMonthChecksum(accounts: readonly SlotlockPartnerAccountMonth[], lines: readonly SlotlockPartnerInvoiceLine[]): string;
+/** `YYYY-MM`, a month that has ended by `now` (UTC): its first day and the next month's. */
+export declare function slotlockClosedMonth(month: string, now: number): {
+    from: string;
+    to: string;
+    next: string;
+};
+/** The month before `now` (UTC), `YYYY-MM`: what a run on the 1st closes. */
+export declare function slotlockPreviousMonth(now: number): string;
+export interface SlotlockPartnerMonthClose {
+    partner: string;
+    month: string;
+    /** Each account's totals as the month was first closed: later runs send the same. */
+    accounts: SlotlockPartnerAccountMonth[];
+    lines: (SlotlockPartnerInvoiceLine & {
+        stripeItem: string | null;
+    })[];
+    checksum: string;
+    /** True when this run closed the month; false when an earlier run had. */
+    closedNow: boolean;
+    /**
+     * The webhook: delivered in this run (a 2xx), delivered by an earlier run, not configured, or
+     * failed (no answer, or another status, in `webhookStatus`), to be sent again by the next run.
+     */
+    webhook: 'delivered' | 'already_delivered' | 'no_webhook' | 'failed';
+    webhookStatus?: number;
+    /** Lines Stripe took in this run, and those still waiting for it (no Stripe key, or a failure). */
+    invoiced: number;
+    pending: number;
+}
+/**
+ * Close one partner's month, as the schema owner (`slotlock partner close`). The first run freezes
+ * it: each account's totals (erased accounts' included), the invoice lines the contract prices them
+ * at and their checksum, in one transaction. Every run then sends usage.period_closed with that same
+ * body until the partner's endpoint takes it (a 2xx), and adds to the partner's next Stripe invoice
+ * each line Stripe has not taken, adopting one it took in a run that stopped before recording it.
+ * Nothing is priced or billed twice, however often or concurrently it runs.
+ */
+export declare function closeSlotlockPartnerMonth(sql: Sql, input: {
+    partnerId: string;
+    month: string;
+    now?: number;
+    /** Stripe: a secret key with read and write access to invoice items. Without it, lines wait. */
+    stripe?: {
+        secretKey: string;
+        fetch?: typeof fetch;
+        apiBase?: string;
+    };
+    /** How the webhook is sent (createSlotlockWebhookSender, which refuses private addresses). */
+    send?: SlotlockWebhookSender;
+}): Promise<SlotlockPartnerMonthClose>;
+/**
+ * The `Slotlock-Client` request field (P5), as metrics count it: the name before any `/version`,
+ * when it is one of the deployment's known integrators (SLOTLOCK_KNOWN_CLIENTS), else `other`, and
+ * `none` without the field. Never anything else from the request.
+ */
+export declare function slotlockClientLabel(field: string | null, known: ReadonlySet<string>): string;