First public release

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 14:49:02 -04:00
commit ff7147296b
14 changed files with 2190 additions and 0 deletions
@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest'
+import { overall, validateReport } from '@extant2000/evidence-record'
+import {
+  assessService,
+  formatService,
+  preflight,
+  stuckJobs,
+  type HostState,
+  type Job,
+  type ProvisioningRequest,
+  type ServiceState,
+} from '../src/index.js'
+
+const NOW = '2026-08-01T12:00:00Z'
+
+const healthy: ServiceState = {
+  workerEnabled: true,
+  provenInProduction: true,
+  verifiesReachability: true,
+}
+
+const host: HostState = { tenants: 10, freeDiskBytes: 50e9, where: 'df -P /data' }
+const request: ProvisioningRequest = {
+  account: 'acme', tenantName: 'acme-prod', existingForAccount: 1,
+  estimatedDiskBytes: 2e9, where: 'provisioning_jobs#j1',
+}
+const limits = { maxTenants: 50, maxPerAccount: 3, minFreeDiskBytes: 10e9 }
+
+describe('dormant is not proven', () => {
+  it('reports a disabled worker as not-assessed, never ready', () => {
+    // Built, enabled and proven in production are three states.
+    const r = assessService({ ...healthy, workerEnabled: false }, { now: NOW })
+    const f = r.findings.find(x => x.id === 'worker/dormant')!
+    expect(f.determination).toBe('not-assessed')
+    expect(f.detail).toContain('the first real tenant becomes the test')
+    expect(overall(r)).toBe('not-assessed')
+  })
+
+  it('distinguishes enabled from proven', () => {
+    const r = assessService({ ...healthy, provenInProduction: false }, { now: NOW })
+    const f = r.findings.find(x => x.id === 'worker/unproven')!
+    expect(f.determination).toBe('not-assessed')
+    expect(f.detail).toContain('the first customer is the integration test')
+  })
+
+  it('says nothing about the worker when it is enabled and proven', () => {
+    const r = assessService(healthy, { now: NOW })
+    expect(r.findings.some(f => f.id.startsWith('worker/'))).toBe(false)
+  })
+})
+
+describe('no ceiling is a denial of service you run against yourself', () => {
+  it('fails when no limits are declared at all', () => {
+    // A quota that was never set is not unlimited, it is unconsidered.
+    const f = preflight(request, host, {})[0]!
+    expect(f.determination).toBe('fail')
+    expect(f.severity).toBe('critical')
+    expect(f.detail).toContain('unlimited, it is unconsidered')
+  })
+
+  it('fails at the host ceiling', () => {
+    expect(preflight(request, { ...host, tenants: 50 }, limits)
+      .some(f => f.id === 'capacity/host' && f.determination === 'fail')).toBe(true)
+  })
+
+  it('fails at the per-account ceiling — one account cannot take the host', () => {
+    expect(preflight({ ...request, existingForAccount: 3 }, host, limits)
+      .some(f => f.id === 'capacity/account' && f.determination === 'fail')).toBe(true)
+  })
+
+  it('fails when provisioning would drop below the disk floor', () => {
+    const f = preflight({ ...request, estimatedDiskBytes: 45e9 }, host, limits)
+      .find(x => x.id === 'capacity/disk')!
+    expect(f.determination).toBe('fail')
+    expect(f.detail).toContain('wedges every container')
+  })
+
+  it('reports unmeasured disk as not-assessed, never plentiful', () => {
+    const f = preflight(request, { ...host, freeDiskBytes: null }, limits)
+      .find(x => x.id === 'capacity/disk')!
+    expect(f.determination).toBe('not-assessed')
+    expect(f.detail).toContain('An unmeasured resource is not a plentiful one')
+  })
+
+  it('reports an unestimated stack the same way', () => {
+    const f = preflight({ ...request, estimatedDiskBytes: null }, host, limits)
+      .find(x => x.id === 'capacity/disk')!
+    expect(f.determination).toBe('not-assessed')
+  })
+
+  it('passes when every limit is satisfied', () => {
+    const out = preflight(request, host, limits)
+    expect(out).toHaveLength(1)
+    expect(out[0]!.determination).toBe('pass')
+  })
+})
+
+describe('a claimed job looks like progress', () => {
+  const job = (p: Partial<Job> = {}): Job =>
+    ({ id: 'j1', state: 'claimed', claimedAt: '2026-08-01T11:00:00Z', claimedBy: 'worker-1', where: 'db', ...p })
+
+  it('finds a job claimed past the limit', () => {
+    // SKIP LOCKED means a dead worker leaves it claimed forever: not queued,
+    // not failed, nothing retrying it.
+    expect(stuckJobs([job()], NOW, 900)).toHaveLength(1)
+    const r = assessService(healthy, { now: NOW, jobs: [job()] })
+    const f = r.findings.find(x => x.id === 'job/j1')!
+    expect(f.determination).toBe('fail')
+    expect(f.severity).toBe('critical')
+    expect(f.detail).toContain('the one state that looks like progress')
+  })
+
+  it('leaves a recently claimed job alone', () => {
+    expect(stuckJobs([job({ claimedAt: '2026-08-01T11:55:00Z' })], NOW, 900)).toHaveLength(0)
+  })
+
+  it('ignores queued, done and failed jobs', () => {
+    for (const state of ['queued', 'done', 'failed'] as const) {
+      expect(stuckJobs([job({ state })], NOW, 900)).toHaveLength(0)
+    }
+  })
+
+  it('honours a custom claim window', () => {
+    expect(stuckJobs([job()], NOW, 7200)).toHaveLength(0)
+    expect(stuckJobs([job()], NOW, 600)).toHaveLength(1)
+  })
+})
+
+describe('provisioned is not reachable', () => {
+  it('reports unverified reachability as not-assessed', () => {
+    const r = assessService({ ...healthy, verifiesReachability: false }, { now: NOW })
+    const f = r.findings.find(x => x.id === 'verify/reachability')!
+    expect(f.determination).toBe('not-assessed')
+    expect(f.detail).toContain('the first person to discover a broken tenant is the tenant')
+  })
+
+  it('says nothing when reachability is verified', () => {
+    expect(assessService(healthy, { now: NOW }).findings.some(f => f.id === 'verify/reachability')).toBe(false)
+  })
+})
+
+describe('conformance with the evidence-record standard', () => {
+  it('a fully healthy service with a valid request passes', () => {
+    const r = assessService(healthy, { now: NOW, request, host, limits })
+    expect(overall(r)).toBe('pass')
+  })
+
+  it('every conclusion carries a citation', () => {
+    expect(validateReport(assessService(
+      { ...healthy, workerEnabled: false },
+      { now: NOW, request, host, limits, jobs: [{ id: 'j1', state: 'claimed', claimedAt: '2026-08-01T09:00:00Z', where: 'db' }] },
+    ))).toEqual([])
+  })
+
+  it('says it gates rather than provisions', () => {
+    expect(formatService(healthy, { now: NOW }))
+      .toContain('gates provisioning; it does not perform it')
+  })
+})