@danceiny/gotry 0.2.0-rc.32 → 0.2.0-rc.33

package/dist/scripts/tenant-seam-quota-tests.js

@@ -0,0 +1,383 @@
+/**
+ * Quotas and metering per tenant and per organization (AaaS A2, docs/rfc/aaas-rfc.md §4.4; threats S-10 and S-11).
+ *
+ * Offline and deterministic: the clock is a number the suite moves by hand, the price table is the real frozen
+ * `data/llm-price-table.json` (ADR-20), and nothing touches a state root or the network.
+ *
+ *   P  policy: invalid limits and an unpriced model are refused at construction
+ *   C  concurrency: tenant, organization and global caps, release, the narrowest scope refuses first
+ *   R  rates: turn rate and bridge job rate in rolling windows, with an exact retry hint
+ *   L  LLM budget: measured usage priced by the frozen table, fail closed on an unpriced model, the worst-case charge
+ *   S  ledger size: per tenant and per organization
+ *   I  isolation: a hot tenant is refused alone, a refusal reserves nothing, counters hold no personal data
+ *
+ * Run: cd ts && npx tsx scripts/tenant-seam-quota-tests.ts
+ */
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadPriceTable } from '../src/llm-price-table.js';
+import { DEFAULT_QUOTA_POLICY, deriveSeamTenant, QuotaExceededError, SeamTenantRequiredError, StaticOrganizationKeyring, TenantQuotas, } from '../src/tenant-seam/index.js';
+import { InvalidTenantIdError, TenantStateError } from '../src/tenant-state/errors.js';
+const TS_ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
+const TABLE = loadPriceTable(join(TS_ROOT, 'data', 'llm-price-table.json'));
+const MODEL = 'deepseek-v4-flash';
+const KEYRING = new StaticOrganizationKeyring({ acme: Buffer.alloc(32, 7), globex: Buffer.alloc(32, 9) });
+let passed = 0;
+function check(label, assertion) {
+    assertion();
+    passed += 1;
+    console.log(`  ok - ${label}`);
+}
+function tenantOf(organization, subject) {
+    return deriveSeamTenant({ organization, issuer: `https://idp.example/${organization}`, subject, scope: 'booking:read' }, KEYRING);
+}
+const POLICY = {
+    tenant: {
+        concurrentTurns: 2,
+        turns: { limit: 3, windowMs: 1_000 },
+        llm: { tokens: 1_000_000, costUsd: 0.5, windowMs: 10_000 },
+        bridgeJobs: { limit: 2, windowMs: 1_000 },
+        ledgerBytes: 1_000,
+    },
+    organization: {
+        concurrentTurns: 3,
+        turns: { limit: 5, windowMs: 1_000 },
+        llm: { tokens: 2_000_000, costUsd: 1, windowMs: 10_000 },
+        bridgeJobs: { limit: 3, windowMs: 1_000 },
+        ledgerBytes: 1_500,
+    },
+    globalConcurrentTurns: 4,
+    unprovenInvocation: { tokens: 10_000, costUsd: 0.05 },
+};
+let now = 0;
+function quotas(policy = POLICY) {
+    now = 0;
+    return new TenantQuotas({ policy, priceTable: TABLE, model: MODEL, clock: () => now });
+}
+function refusal(action) {
+    try {
+        action();
+    }
+    catch (error) {
+        assert.ok(error instanceof QuotaExceededError, `expected a QuotaExceededError, got ${String(error)}`);
+        return error;
+    }
+    throw new assert.AssertionError({ message: 'expected the quota to refuse' });
+}
+function snapshotOf(q, tenant) {
+    const key = `${tenant.organization}/${tenant.ledgerTenant}`;
+    return q.snapshot().tenants.find((entry) => entry.key === key);
+}
+console.log('P  policy');
+check('P1 a tenant cap above its organization cap, and an organization cap above the global cap, are refused', () => {
+    assert.throws(() => new TenantQuotas({ policy: { ...POLICY, tenant: { ...POLICY.tenant, concurrentTurns: 4 } }, priceTable: TABLE, model: MODEL }), /tenant\.concurrentTurns must not exceed/);
+    assert.throws(() => new TenantQuotas({ policy: { ...POLICY, globalConcurrentTurns: 2 }, priceTable: TABLE, model: MODEL }), /organization\.concurrentTurns must not exceed/);
+});
+check('P2 a zero, negative, fractional or non-numeric limit is refused', () => {
+    for (const bad of [0, -1, 1.5, Number.NaN, '3']) {
+        assert.throws(() => new TenantQuotas({ policy: { ...POLICY, tenant: { ...POLICY.tenant, turns: { limit: bad, windowMs: 1_000 } } }, priceTable: TABLE, model: MODEL }), /positive integer/, `limit ${String(bad)}`);
+    }
+    assert.throws(() => new TenantQuotas({ policy: { ...POLICY, unprovenInvocation: { tokens: 1, costUsd: 0 } }, priceTable: TABLE, model: MODEL }), /positive number/);
+});
+check('P3 a model the frozen table does not price stops construction before any spend (ADR-20)', () => {
+    assert.throws(() => new TenantQuotas({ policy: POLICY, priceTable: TABLE, model: 'model-nobody-priced' }), /no entry for model/);
+});
+check('P4 the shipped default policy is valid and constructs', () => {
+    const q = new TenantQuotas({ policy: DEFAULT_QUOTA_POLICY, priceTable: TABLE, model: MODEL, clock: () => 0 });
+    q.admitTurn(tenantOf('acme', 'default-policy')).release();
+});
+console.log('P  no raw tenant');
+check('P5 every quota call takes a tenant derived at the seam; a string, a look-alike object or nothing is refused', () => {
+    const q = quotas();
+    const real = tenantOf('acme', 'u1');
+    const lookalike = { organization: real.organization, ledgerTenant: real.ledgerTenant };
+    for (const forged of [real.ledgerTenant, lookalike, JSON.parse(JSON.stringify(real)), null, undefined, 7]) {
+        assert.throws(() => q.admitTurn(forged), SeamTenantRequiredError);
+        assert.throws(() => q.recordLlmUsage(forged, MODEL, { inputTokens: 1, outputTokens: 1 }), SeamTenantRequiredError);
+        assert.throws(() => q.chargeUnprovenInvocation(forged), SeamTenantRequiredError);
+        assert.throws(() => q.admitBridgeJob(forged), SeamTenantRequiredError);
+        assert.throws(() => q.observeLedgerBytes(forged, 1), SeamTenantRequiredError);
+        assert.throws(() => q.forgetTenant(forged), SeamTenantRequiredError);
+    }
+    assert.equal(q.snapshot().tenants.length, 0, 'a refused forgery creates no account');
+});
+console.log('C  concurrency');
+check('C1 a tenant at its concurrent-turn cap is refused with its own scope, and a release frees exactly one slot', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    const first = q.admitTurn(t);
+    q.admitTurn(t);
+    const error = refusal(() => q.admitTurn(t));
+    assert.deepEqual([error.scope, error.dimension, error.limit], ['tenant', 'concurrent_turns', 2]);
+    first.release();
+    q.admitTurn(t);
+    assert.equal(refusal(() => q.admitTurn(t)).dimension, 'concurrent_turns');
+});
+check('C2 releasing a permit twice frees one slot, not two', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    const a = q.admitTurn(t);
+    q.admitTurn(t);
+    a.release();
+    a.release();
+    q.admitTurn(t);
+    const error = refusal(() => q.admitTurn(t));
+    assert.deepEqual([error.scope, error.dimension], ['tenant', 'concurrent_turns'], 'the double release did not open a third slot');
+});
+check('C3 the organization cap refuses a tenant that is within its own, naming the organization', () => {
+    const q = quotas();
+    const [u1, u2, u3] = [tenantOf('acme', 'u1'), tenantOf('acme', 'u2'), tenantOf('acme', 'u3')];
+    q.admitTurn(u1);
+    q.admitTurn(u1);
+    q.admitTurn(u2);
+    const error = refusal(() => q.admitTurn(u3));
+    assert.deepEqual([error.scope, error.dimension, error.limit], ['organization', 'concurrent_turns', 3]);
+    q.admitTurn(tenantOf('globex', 'u1'));
+});
+check('C4 the global cap refuses when no organization is over its own', () => {
+    const q = quotas();
+    q.admitTurn(tenantOf('acme', 'u1'));
+    q.admitTurn(tenantOf('acme', 'u2'));
+    q.admitTurn(tenantOf('globex', 'u1'));
+    q.admitTurn(tenantOf('globex', 'u2'));
+    const error = refusal(() => q.admitTurn(tenantOf('globex', 'u3')));
+    assert.deepEqual([error.scope, error.dimension, error.limit], ['global', 'concurrent_turns', 4]);
+});
+console.log('R  rates');
+check('R1 the turn rate is a rolling window with an exact retry hint, and the oldest entry leaves on the boundary', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    for (const at of [0, 100, 200]) {
+        now = at;
+        q.admitTurn(t).release();
+    }
+    now = 300;
+    const error = refusal(() => q.admitTurn(t));
+    assert.deepEqual([error.scope, error.dimension, error.limit, error.retryAfterMs, error.retryAfterSeconds], ['tenant', 'turn_rate', 3, 700, 1]);
+    now = 999;
+    assert.equal(refusal(() => q.admitTurn(t)).retryAfterMs, 1, 'one millisecond before the boundary');
+    now = 1_000;
+    q.admitTurn(t).release();
+});
+check('R2 the organization rate refuses tenants that are each within their own', () => {
+    const q = quotas();
+    let tick = 0;
+    for (const [subject, turns] of [['u1', 2], ['u2', 2], ['u3', 1]]) {
+        for (let i = 0; i < turns; i += 1) {
+            now = tick++;
+            q.admitTurn(tenantOf('acme', subject)).release();
+        }
+    }
+    now = 10;
+    const error = refusal(() => q.admitTurn(tenantOf('acme', 'u4')));
+    assert.deepEqual([error.scope, error.dimension, error.limit], ['organization', 'turn_rate', 5]);
+});
+check('R3 the bridge job rate counts per tenant and per organization, and an organization-only caller counts at the organization', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    q.admitBridgeJob(t);
+    q.admitBridgeJob(t);
+    const own = refusal(() => q.admitBridgeJob(t));
+    assert.deepEqual([own.scope, own.dimension, own.limit], ['tenant', 'bridge_jobs', 2]);
+    q.admitBridgeJob(tenantOf('acme', 'u2'));
+    const org = refusal(() => q.admitBridgeJob(tenantOf('acme', 'u3')));
+    assert.deepEqual([org.scope, org.dimension, org.limit], ['organization', 'bridge_jobs', 3]);
+    q.admitOrganizationBridgeJob('globex');
+    q.admitOrganizationBridgeJob('globex');
+    q.admitOrganizationBridgeJob('globex');
+    assert.equal(refusal(() => q.admitOrganizationBridgeJob('globex')).scope, 'organization');
+});
+check('R4 an organization id that is not path-safe is refused before an account exists', () => {
+    const q = quotas();
+    for (const bad of ['../x', 'ACME', '', 'a/b', 'a'.repeat(64), 'acme\n']) {
+        assert.throws(() => q.admitOrganizationBridgeJob(bad), InvalidTenantIdError, JSON.stringify(bad));
+    }
+    assert.equal(q.snapshot().organizations.length, 0);
+});
+console.log('L  LLM budget');
+check('L1 measured usage is priced by the frozen table: fresh input, cache-read input and output, and aliases resolve', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    q.recordLlmUsage(t, MODEL, { inputTokens: 100_000, cacheReadTokens: 200_000, outputTokens: 50_000 });
+    const expected = (100_000 * 0.44 + 200_000 * 0.014 + 50_000 * 1.32) / 1_000_000;
+    const entry = snapshotOf(q, t);
+    assert.equal(entry.llmTokens, 350_000);
+    assert.equal(entry.llmCostUsd, Number(expected.toFixed(6)));
+    q.recordLlmUsage(t, 'deepseek-chat', { inputTokens: 100_000, outputTokens: 0 });
+    assert.equal(snapshotOf(q, t).llmCostUsd, Number((expected + 0.044).toFixed(6)), 'the generation alias prices as its target');
+    assert.equal(q.snapshot().organizations[0].llmTokens, 450_000, 'the organization is charged too');
+});
+check('L2 an unpriced model, a malformed count or a report of zero tokens is refused and charges nothing', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    assert.throws(() => q.recordLlmUsage(t, 'model-nobody-priced', { inputTokens: 1, outputTokens: 1 }), /no entry for model/);
+    // no completion costs nothing: a relay that answers zeros is not measuring, and the caller must then charge the worst case
+    assert.throws(() => q.recordLlmUsage(t, MODEL, { inputTokens: 0, outputTokens: 0 }), /zero tokens/);
+    assert.throws(() => q.recordLlmUsage(t, MODEL, { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 }), /zero tokens/);
+    for (const bad of [-1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 2]) {
+        assert.throws(() => q.recordLlmUsage(t, MODEL, { inputTokens: bad, outputTokens: 1 }), RangeError, String(bad));
+        assert.throws(() => q.recordLlmUsage(t, MODEL, { inputTokens: 1, outputTokens: bad }), RangeError, String(bad));
+        assert.throws(() => q.recordLlmUsage(t, MODEL, { inputTokens: 1, outputTokens: 1, cacheReadTokens: bad }), RangeError, String(bad));
+    }
+    const entry = snapshotOf(q, t);
+    assert.ok(!entry || (entry.llmTokens === 0 && entry.llmCostUsd === 0));
+});
+check('L3 the token budget refuses the next turn once spent, names the dimension, and reopens when the charge ages out', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    q.recordLlmUsage(t, MODEL, { inputTokens: 600_000, outputTokens: 400_000 });
+    now = 4_000;
+    const error = refusal(() => q.admitTurn(t));
+    assert.deepEqual([error.scope, error.dimension, error.limit, error.retryAfterMs], ['tenant', 'llm_tokens', 1_000_000, 6_000]);
+    now = 10_000;
+    q.admitTurn(t).release();
+});
+check('L4 the cost budget refuses on cost alone, in dollars, before the token budget is touched', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    q.recordLlmUsage(t, MODEL, { inputTokens: 0, outputTokens: 400_000 });
+    assert.equal(snapshotOf(q, t).llmCostUsd, 0.528);
+    const error = refusal(() => q.admitTurn(t));
+    assert.deepEqual([error.scope, error.dimension, error.limit], ['tenant', 'llm_cost', 0.5]);
+});
+check('L5 the organization budget is the sum of its tenants and refuses a tenant that spent nothing', () => {
+    const q = quotas();
+    for (const subject of ['u1', 'u2', 'u3'])
+        q.recordLlmUsage(tenantOf('acme', subject), MODEL, { inputTokens: 700_000, outputTokens: 0 });
+    const error = refusal(() => q.admitTurn(tenantOf('acme', 'fresh')));
+    assert.deepEqual([error.scope, error.dimension], ['organization', 'llm_tokens']);
+    q.admitTurn(tenantOf('globex', 'fresh')).release();
+});
+check('L6 an invocation that reported nothing is charged the configured worst case, never zero', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    q.chargeUnprovenInvocation(t);
+    const entry = snapshotOf(q, t);
+    assert.deepEqual([entry.llmTokens, entry.llmCostUsd], [10_000, 0.05]);
+    for (let i = 0; i < 9; i += 1)
+        q.chargeUnprovenInvocation(t);
+    assert.equal(refusal(() => q.admitTurn(t)).dimension, 'llm_cost', 'ten silent invocations exhaust the cost budget');
+});
+console.log('S  ledger size');
+check('S1 a tenant ledger at its limit is refused with a long hint, one byte under is not', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'u1');
+    q.observeLedgerBytes(t, 999);
+    const error = refusal(() => q.observeLedgerBytes(t, 1_000));
+    assert.deepEqual([error.scope, error.dimension, error.limit], ['tenant', 'ledger_size', 1_000]);
+    assert.ok(error.retryAfterSeconds >= 3_600);
+});
+check('S2 the organization limit is the sum of its tenants served here, and a forget takes a tenant out of it', () => {
+    const q = quotas();
+    const [u1, u2] = [tenantOf('acme', 'u1'), tenantOf('acme', 'u2')];
+    q.observeLedgerBytes(u1, 800);
+    const error = refusal(() => q.observeLedgerBytes(u2, 800));
+    assert.deepEqual([error.scope, error.dimension, error.limit], ['organization', 'ledger_size', 1_500]);
+    q.forgetTenant(u1);
+    q.observeLedgerBytes(u2, 800);
+    q.observeLedgerBytes(u2, 900);
+    assert.throws(() => q.observeLedgerBytes(u2, -1), RangeError);
+});
+console.log('I  isolation');
+check('I1 a hot tenant is refused alone: its flood changes nothing for a neighbour, another organization, or the counters of either', () => {
+    const q = quotas();
+    const hot = tenantOf('acme', 'hot');
+    let admitted = 0;
+    let refused = 0;
+    for (let i = 0; i < 1_000; i += 1) {
+        try {
+            q.admitTurn(hot);
+            admitted += 1;
+        }
+        catch (error) {
+            assert.ok(error instanceof QuotaExceededError);
+            assert.equal(error.scope, 'tenant');
+            refused += 1;
+        }
+    }
+    assert.deepEqual([admitted, refused], [2, 998]);
+    const neighbour = tenantOf('acme', 'neighbour');
+    const other = tenantOf('globex', 'neighbour');
+    q.admitTurn(neighbour).release();
+    q.admitTurn(other).release();
+    assert.equal(snapshotOf(q, neighbour).rejected.concurrent_turns, 0);
+    assert.equal(snapshotOf(q, other).rejected.concurrent_turns, 0);
+    assert.equal(snapshotOf(q, hot).rejected.concurrent_turns, 998);
+});
+check('I2 a refusal reserves nothing: no slot, no rate entry, no account for a fresh tenant, no counter moves except the organization\'s refusal count', () => {
+    const q = quotas();
+    const [u1, u2, u3] = [tenantOf('acme', 'u1'), tenantOf('acme', 'u2'), tenantOf('acme', 'u3')];
+    q.admitTurn(u1);
+    q.admitTurn(u1);
+    q.admitTurn(u2);
+    const before = JSON.stringify(q.snapshot());
+    refusal(() => q.admitTurn(u3));
+    const after = q.snapshot();
+    assert.equal(after.globalActiveTurns, 3);
+    assert.equal(snapshotOf(q, u3), undefined, 'a refused fresh tenant is not remembered at all');
+    const organization = after.organizations.find((entry) => entry.key === 'acme');
+    assert.equal(organization.activeTurns, 3);
+    assert.equal(organization.turnsInWindow, 3);
+    assert.equal(organization.rejected.concurrent_turns, 1);
+    assert.notEqual(before, JSON.stringify(after), 'only the refusal count moved');
+});
+check('I3 counters are keyed by the organization and the HMAC tenant id and hold no subject, issuer or scope', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'alice@example.com');
+    q.admitTurn(t).release();
+    q.recordLlmUsage(t, MODEL, { inputTokens: 1, outputTokens: 1 });
+    const text = JSON.stringify(q.snapshot());
+    assert.match(q.snapshot().tenants[0].key, /^acme\/t-[0-9a-f]{32}$/);
+    for (const secret of ['alice', 'example.com', 'idp.example', 'booking:read'])
+        assert.ok(!text.includes(secret), `snapshot leaks ${secret}`);
+});
+check('I4 idle accounts are swept and take their ledger size out of the organization total; a live turn keeps its account', () => {
+    const q = quotas();
+    const keeper = tenantOf('acme', 'keeper');
+    q.observeLedgerBytes(keeper, 10);
+    assert.equal(q.snapshot().organizations.find((entry) => entry.key === 'acme')?.ledgerBytes, 10);
+    const live = tenantOf('acme', 'live');
+    const held = q.admitTurn(live);
+    for (let i = 0; i < 1_100; i += 1) {
+        now = i * 5_000;
+        q.admitTurn(tenantOf(i % 2 === 0 ? 'acme' : 'globex', `churn-${i}`)).release();
+    }
+    const keys = new Set(q.snapshot().tenants.map((entry) => entry.key));
+    assert.ok(keys.size < 200, `idle tenants were swept at the thousandth admission (${keys.size} left of 1102)`);
+    assert.ok(!keys.has(`acme/${keeper.ledgerTenant}`), 'an idle tenant is swept although its ledger has a size');
+    assert.ok(keys.has(`acme/${live.ledgerTenant}`), 'a live turn keeps its account');
+    assert.equal(q.snapshot().organizations.find((entry) => entry.key === 'acme')?.ledgerBytes, 0, 'the swept ledger left the organization total');
+    held.release();
+});
+check('I6 a fresh tenant that is refused leaves no account behind, and refused attempts advance the sweep', () => {
+    // rates are out of the way: only the organization's concurrency cap (3) refuses here
+    const q = quotas({ ...POLICY, tenant: { ...POLICY.tenant, turns: { limit: 1_000_000, windowMs: 1_000 } }, organization: { ...POLICY.organization, turns: { limit: 1_000_000, windowMs: 1_000 } } });
+    const idleTenants = Array.from({ length: 10 }, (_, n) => tenantOf('acme', `early-${n}`));
+    for (const tenant of idleTenants)
+        q.admitTurn(tenant).release();
+    const holders = [tenantOf('acme', 'h1'), tenantOf('acme', 'h2'), tenantOf('acme', 'h3')].map((tenant) => q.admitTurn(tenant));
+    // the organization cap (3) is full: every further tenant is refused, and none of them may be remembered
+    now = 1_000_000;
+    for (let i = 0; i < 1_100; i += 1) {
+        refusal(() => q.admitTurn(tenantOf('acme', `flood-${i}`)));
+        assert.ok(q.snapshot().tenants.length <= 13, 'a refused tenant was registered');
+    }
+    const keys = q.snapshot().tenants.map((entry) => entry.key);
+    assert.ok(!idleTenants.some((tenant) => keys.includes(`acme/${tenant.ledgerTenant}`)), 'the refused attempts advanced the sweep: the idle tenants are gone');
+    assert.equal(keys.length, 3, 'only the three live turns hold an account');
+    for (const holder of holders)
+        holder.release();
+});
+check('I5 a refusal is a typed tenant-state error with a code, a scope and a hint, and its message names no person', () => {
+    const q = quotas();
+    const t = tenantOf('acme', 'alice@example.com');
+    q.admitTurn(t);
+    q.admitTurn(t);
+    const error = refusal(() => q.admitTurn(t));
+    assert.ok(error instanceof TenantStateError);
+    assert.equal(error.code, 'GOTRY_QUOTA_EXCEEDED');
+    assert.ok(Number.isInteger(error.retryAfterMs) && error.retryAfterMs >= 1);
+    assert.ok(!error.message.includes('alice') && !error.message.includes(t.ledgerTenant));
+});
+console.log(`tenant-seam quota tests: ${passed} checks passed`);

package/dist/scripts/tenant-seam-test-kit.js

@@ -0,0 +1,292 @@
+/**
+ * Shared fixtures of the AaaS A2 seam suites: a fleet of replicas that serve the Booking Copilot surface in its
+ * multi-tenant form over real HTTP, with a credential table standing in for the A3 authenticator, a scripted planner
+ * standing in for the model, and the helpers to read what landed in each tenant's own ledger.
+ *
+ * Everything is offline and deterministic: manual clocks, a directory for the object store, SQLite lease files, one
+ * state root per replica under a caller-owned temp directory. Nothing here reads the founder's runtime state.
+ */
+import assert from 'node:assert/strict';
+import { request as httpRequest } from 'node:http';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BOOKING_SURFACE_SCHEMA_SHA256, BOOKING_SURFACE_SCHEMA_VERSION } from '../src/booking-surface/contracts.js';
+import { startBookingCopilotServer } from '../src/booking-surface/server.js';
+import { BookingTenancy, sharedPlannerProvider } from '../src/booking-surface/tenancy.js';
+import { loadPriceTable } from '../src/llm-price-table.js';
+import { deriveSeamTenant, StaticOrganizationKeyring, TenantQuotas, } from '../src/tenant-seam/index.js';
+import { DirDurableStore } from '../src/tenant-state/durable-store.js';
+import { SqliteLeaseStore } from '../src/tenant-state/lease-store.js';
+import { TenantRouter } from '../src/tenant-state/tenant-router.js';
+import { ManualClock } from './tenant-state-test-kit.js';
+export const TS_ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
+export const PRICE_TABLE = loadPriceTable(join(TS_ROOT, 'data', 'llm-price-table.json'));
+export const MODEL = 'deepseek-v4-flash';
+export const TTL = 10_000;
+export const MARGIN = 2_000;
+export const KEYRING = new StaticOrganizationKeyring({ acme: Buffer.alloc(32, 0x31), globex: Buffer.alloc(32, 0x32) });
+/** Credential -> caller. This table is the test double of the A3 authenticator; the seam trusts nothing else. */
+export const CALLERS = {
+    'cred-acme-alice': { organization: 'acme', issuer: 'https://idp.acme.example', subject: 'alice', scope: 'booking:read' },
+    'cred-acme-bob': { organization: 'acme', issuer: 'https://idp.acme.example', subject: 'bob', scope: 'booking:read' },
+    'cred-acme-carol': { organization: 'acme', issuer: 'https://idp.acme.example', subject: 'carol', scope: 'booking:read' },
+    'cred-acme-alice-elsewhere': { organization: 'acme', issuer: 'https://other-idp.acme.example', subject: 'alice', scope: 'booking:read' },
+    'cred-globex-alice': { organization: 'globex', issuer: 'https://idp.globex.example', subject: 'alice', scope: 'booking:read' },
+};
+export const ROOMY = {
+    tenant: {
+        concurrentTurns: 4,
+        turns: { limit: 1_000, windowMs: 60_000 },
+        llm: { tokens: 1_000_000_000, costUsd: 1_000, windowMs: 3_600_000 },
+        bridgeJobs: { limit: 100, windowMs: 60_000 },
+        ledgerBytes: 1_000_000_000,
+    },
+    organization: {
+        concurrentTurns: 16,
+        turns: { limit: 10_000, windowMs: 60_000 },
+        llm: { tokens: 1_000_000_000, costUsd: 1_000, windowMs: 3_600_000 },
+        bridgeJobs: { limit: 1_000, windowMs: 60_000 },
+        ledgerBytes: 1_000_000_000_000,
+    },
+    globalConcurrentTurns: 64,
+    unprovenInvocation: { tokens: 10_000, costUsd: 0.05 },
+};
+export function tenantOf(credential) {
+    const caller = CALLERS[credential];
+    assert.ok(caller, `unknown test credential ${credential}`);
+    return deriveSeamTenant(caller, KEYRING);
+}
+// ---- requests ---------------------------------------------------------------------------
+export const workspace = (contextRef, currency = 'AED') => ({
+    schemaVersion: 'booking.surface',
+    contextRef,
+    surface: 'tenant',
+    revision: 0,
+    locale: 'en-US',
+    currency,
+    searchDraft: {},
+    results: { status: 'idle' },
+    visibleHotels: [],
+    loadedOffers: [],
+    shortlistedOfferRefs: [],
+    capabilities: { surface: 'tenant', allowedActions: ['search.run'] },
+});
+export const userTurn = (taskId, contextRef, text, currency = 'AED') => ({
+    schemaVersion: 'booking.surface',
+    kind: 'user.turn',
+    taskId,
+    turnId: `${taskId}-turn-1`,
+    workspace: workspace(contextRef, currency),
+    request: { text },
+});
+export const ingressTurn = (requestKey, taskHandle, text) => ({
+    schemaVersion: 'booking.surface',
+    kind: 'user.turn.ingress',
+    requestKey,
+    taskHandle,
+    surfaceHint: 'tenant',
+    workspace: { schemaVersion: 'booking.surface', revision: 0, locale: 'en-US', currency: 'AED', searchDraft: {}, results: { status: 'idle' }, visibleHotels: [], loadedOffers: [], shortlistedOfferRefs: [] },
+    request: { text },
+});
+export function sseEvents(text) {
+    return text.split('\n\n').filter((block) => block.trim() !== '').map((block) => {
+        const lines = block.split('\n');
+        const event = lines.find((line) => line.startsWith('event: '))?.slice(7) ?? '';
+        const data = lines.find((line) => line.startsWith('data: '))?.slice(6) ?? 'null';
+        return { event, data: JSON.parse(data) };
+    });
+}
+/** Every key name anywhere in a JSON value. */
+export function keyNamesOf(value, into = new Set()) {
+    if (Array.isArray(value))
+        for (const item of value)
+            keyNamesOf(item, into);
+    else if (value && typeof value === 'object') {
+        for (const [key, child] of Object.entries(value)) {
+            into.add(key);
+            keyNamesOf(child, into);
+        }
+    }
+    return into;
+}
+export function gate() {
+    let open;
+    let entered;
+    const wait = new Promise((resolve) => { open = resolve; });
+    const enteredPromise = new Promise((resolve) => { entered = resolve; });
+    return { gate: { entered: enteredPromise, open }, wait, markEntered: entered };
+}
+function textOf(turn) {
+    return turn.kind === 'user.turn' || turn.kind === 'user.turn.ingress' ? turn.request.text : '';
+}
+export function searchRunDecision(taskId, contextRef, revision, who) {
+    return {
+        kind: 'operation',
+        action: {
+            schemaVersion: 'booking.surface',
+            kind: 'search.run',
+            actionId: `action-${taskId}`,
+            contextRef,
+            expectedRevision: revision,
+            reason: `Run the authoritative workspace search for ${who}`,
+            factRefs: [],
+            input: {},
+        },
+        intent: { schemaVersion: 'booking.intent.v1', target: 'search.results' },
+    };
+}
+export function makePlanner() {
+    const holds = [];
+    const kit = {
+        calls: [],
+        factoryCalls: 0,
+        closes: 0,
+        script: null,
+        hold(pattern) {
+            const held = gate();
+            holds.push({ pattern, gate: held });
+            return held.gate;
+        },
+        releaseAll() {
+            for (const held of holds)
+                held.gate.gate.open();
+        },
+        factory: () => {
+            kit.factoryCalls += 1;
+            const session = {
+                async next({ turn, task }) {
+                    const text = textOf(turn);
+                    kit.calls.push({ taskId: task.taskId, contextRef: task.contextRef, text });
+                    for (const held of holds) {
+                        if (held.pattern.test(text)) {
+                            held.gate.markEntered();
+                            await held.gate.wait;
+                        }
+                    }
+                    if (kit.script)
+                        return kit.script({ turn, taskId: task.taskId, contextRef: task.contextRef, revision: task.revision, text });
+                    // A receipt closes the task; anything else runs the search for whoever the text says it is for.
+                    if (turn.kind === 'action.receipt.continuation') {
+                        return [
+                            { kind: 'explanation', explanation: { text: 'The search ran.', factRefs: [] } },
+                            { kind: 'terminal', terminal: { status: 'completed', summary: 'Stopped at the requested search result.', factRefs: [] } },
+                        ];
+                    }
+                    return [searchRunDecision(task.taskId, task.contextRef, task.revision, text.split(' as ')[1] ?? 'anyone')];
+                },
+                async close() { kit.closes += 1; },
+            };
+            return session;
+        },
+    };
+    return kit;
+}
+export function makeFleet(dir, cleanups) {
+    const storeClock = new ManualClock(1_000_000);
+    const leases = new SqliteLeaseStore({ path: join(dir, 'leases.db'), nowMs: () => storeClock.nowMs() });
+    cleanups.push(() => leases.close());
+    const clocks = [];
+    return {
+        dir,
+        storeClock,
+        leases,
+        durable: new DirDurableStore(join(dir, 'durable')),
+        clocks,
+        advance(ms, frozen = []) {
+            storeClock.advance(ms);
+            for (const clock of clocks)
+                if (!frozen.includes(clock))
+                    clock.advance(ms);
+        },
+    };
+}
+export async function makeService(fleet, id, cleanups, options = {}) {
+    const clock = new ManualClock(5_000);
+    fleet.clocks.push(clock);
+    const stateRoot = join(fleet.dir, 'nodes', id);
+    const router = new TenantRouter({
+        stateRoot, replicaId: id, leases: fleet.leases, durable: fleet.durable, ttlMs: TTL, marginMs: MARGIN, clock, autoRenew: false,
+    });
+    const quotas = new TenantQuotas({ policy: options.policy ?? ROOMY, priceTable: PRICE_TABLE, model: MODEL, clock: () => clock.nowMs() });
+    const planner = options.planner ?? makePlanner();
+    const seenHeaders = [];
+    const bound = [];
+    const authenticator = {
+        authenticate(request) {
+            seenHeaders.push(Object.keys(request.headers).sort());
+            const match = /^Bearer (cred-[a-z0-9-]+)$/.exec(String(request.headers.authorization ?? ''));
+            return match ? (CALLERS[match[1]] ?? null) : null;
+        },
+    };
+    const binding = {
+        bind(input, principal) {
+            bound.push({ requestKey: input.requestKey, principal: { ...principal } });
+            return { taskId: 'task-bound', turnId: `turn-${input.requestKey}`, contextRef: 'ctx-bound', surface: 'tenant', allowedActions: ['search.run'] };
+        },
+    };
+    const tenancy = new BookingTenancy({
+        authenticator,
+        keyring: KEYRING,
+        router,
+        quotas,
+        planners: options.provider ?? sharedPlannerProvider(planner.factory),
+        ...(options.ingress ? { ingressBinding: binding } : {}),
+    });
+    const server = await startBookingCopilotServer({ tenancy: options.wrapTenancy ? options.wrapTenancy(tenancy) : tenancy, host: '127.0.0.1', port: 0 });
+    const endpoint = `http://127.0.0.1:${server.port}/a2a/booking-copilot/turn`;
+    const schemaHeaders = { 'x-booking-surface-version': BOOKING_SURFACE_SCHEMA_VERSION, 'x-booking-surface-schema-sha256': BOOKING_SURFACE_SCHEMA_SHA256 };
+    let closed = false;
+    const service = {
+        id, stateRoot, router, quotas, tenancy, planner, clock, server, endpoint, seenHeaders, bound,
+        async post(body, credential, extraHeaders = {}) {
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...schemaHeaders, ...(credential ? { authorization: `Bearer ${credential}` } : {}), ...extraHeaders },
+                body: typeof body === 'string' ? body : JSON.stringify(body),
+            });
+            const headers = {};
+            response.headers.forEach((value, key) => { headers[key] = value; });
+            return { status: response.status, headers, text: await response.text() };
+        },
+        postRaw(body, credential, onData) {
+            return new Promise((resolve, reject) => {
+                const payload = JSON.stringify(body);
+                const req = httpRequest(endpoint, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload), authorization: `Bearer ${credential}`, ...schemaHeaders },
+                }, (res) => {
+                    let text = '';
+                    res.setEncoding('utf8');
+                    res.on('data', (chunk) => { text += chunk; onData?.(chunk); });
+                    res.on('end', () => resolve({ status: res.statusCode ?? 0, text, ended: 'end' }));
+                    res.on('aborted', () => resolve({ status: res.statusCode ?? 0, text, ended: 'aborted' }));
+                    res.on('error', () => resolve({ status: res.statusCode ?? 0, text, ended: 'aborted' }));
+                    res.on('close', () => resolve({ status: res.statusCode ?? 0, text, ended: res.complete ? 'end' : 'aborted' }));
+                });
+                req.on('error', reject);
+                req.end(payload);
+            });
+        },
+        handleOf(credential) {
+            const tenant = tenantOf(credential);
+            return router.handleOf(tenant.organization, tenant.ledgerTenant);
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            planner.releaseAll();
+            await server.close().catch(() => undefined);
+            await tenancy.close().catch(() => undefined);
+        },
+    };
+    cleanups.push(() => service.close());
+    return service;
+}
+/** All rows of a tenant's ledger, or `null` when this replica has not opened the tenant (so nothing was written here). */
+export function rowsOf(service, credential) {
+    const handle = service.handleOf(credential);
+    if (!handle)
+        return null;
+    return handle.run((ledger) => ledger.db.prepare('SELECT seq, kind, run_id, idem_key, tenant_id, payload FROM events ORDER BY seq').all());
+}