@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.15

package/src/extensions/scaffold-convex.mjs

@@ -0,0 +1,130 @@
+// Source templates only. The CLI never starts a provider or provisions an account.
+export function convexProjectFiles() {
+  return {
+    dependencies: { convex: '1.46.0' },
+    files: {
+      'convex.json': JSON.stringify({ functions: 'convex/' }, null, 2) + '\n',
+      'src/client.ts': "export { createExtensionClient } from '@mnstry/atelier/extensions/client'\n",
+      'convex/schema.ts': "export { default } from '../migrations/001-schema'\n",
+      'migrations/001-schema.ts': `import { defineSchema, defineTable } from 'convex/server'
+import { v } from 'convex/values'
+const scope = { installationId: v.string(), tenantRef: v.string(), subjectRef: v.string() }
+export default defineSchema({
+  extensionCounters: defineTable({ ...scope, value: v.number() }).index('by_scope', ['installationId', 'tenantRef', 'subjectRef']),
+  extensionOperations: defineTable({ ...scope, operationId: v.string(), actionId: v.string(), generation: v.string(),
+    releaseDigest: v.string(), payloadDigest: v.string(), result: v.any(), resultDigest: v.string() })
+    .index('by_scope_operation', ['installationId', 'tenantRef', 'subjectRef', 'operationId']),
+})
+`,
+      'convex/backend.ts': `import { internalMutation, internalQuery } from './_generated/server'
+import type { DataModel } from './_generated/dataModel'
+import type { MutationCtx } from './_generated/server'
+import { v } from 'convex/values'
+import manifest from '../extension.manifest.json'
+import { canonicalJson, exact, ExtensionError, parseManifest, parseProviderOperationProof, type Json } from '@mnstry/atelier/extensions'
+import { defineConvexExtension, runConvexInvocation, onceConvexOperation, lookupConvexOperation, convexHealth,
+  type ConvexVerifierOptions } from '@mnstry/atelier/extensions/convex'
+import type { VerifiedScope } from '@mnstry/atelier/extensions/server'
+const counter = (value: unknown) => {
+  const input = exact(value, ['value'])
+  if (!Number.isSafeInteger(input.value) || Number(input.value) < 0 || Number(input.value) > 1000000) throw new ExtensionError('invalid-input')
+  return { value: Number(input.value) }
+}
+const empty = (value: unknown) => { exact(value, []); return {} }
+const json = (value: unknown): Json => JSON.parse(canonicalJson(value))
+const scoped = (context: MutationCtx, scope: VerifiedScope) => context.db.query('extensionCounters').withIndex('by_scope',
+  query => query.eq('installationId', scope.installationId).eq('tenantRef', scope.tenantRef).eq('subjectRef', scope.subjectRef))
+export function extension(consume?: ConvexVerifierOptions['consume']) {
+  const keys: Record<string, JsonWebKey> = JSON.parse(process.env.EXTENSION_ROOT_PUBLIC_KEYS ?? '{}')
+  return defineConvexExtension<DataModel>({ manifest: parseManifest(manifest), verifier: {
+    issuer: process.env.EXTENSION_ROOT_ISSUER ?? '', audience: process.env.EXTENSION_AUDIENCE ?? '',
+    installationId: process.env.EXTENSION_INSTALLATION_ID ?? '', releaseDigest: manifest.releaseDigest,
+    keys: new Map(Object.entries(keys)), consume,
+  }, actions: {
+    'counter.set': { input: counter, output: counter, run: ({ context, scope }, input) => onceConvexOperation(context, scope, input, async () => {
+      const row = await scoped(context, scope).unique()
+      if (row) await context.db.patch(row._id, input)
+      else await context.db.insert('extensionCounters', { installationId: scope.installationId, tenantRef: scope.tenantRef, subjectRef: scope.subjectRef, ...input })
+      return input
+    }) },
+    'counter.get': { input: empty, output: counter, run: async ({ context, scope }) => ({ value: (await scoped(context, scope).unique())?.value ?? 0 }) },
+    'counter.export': { input: empty, output: json, run: async ({ context, scope }) => ({ schema: 'sample.counter-export/v1', value: (await scoped(context, scope).unique())?.value ?? 0 }) },
+    'counter.delete': { input: empty, output: json, run: ({ context, scope }, input) => onceConvexOperation(context, scope, input, async () => {
+      const rows = await context.db.query('extensionOperations').withIndex('by_scope_operation',
+        query => query.eq('installationId', scope.installationId).eq('tenantRef', scope.tenantRef).eq('subjectRef', scope.subjectRef)).take(501)
+      // A larger history needs an explicitly designed paginated erasure workflow.
+      // Refuse atomically instead of claiming a partial delete is complete.
+      if (rows.length > 500) throw new ExtensionError('unavailable', 503)
+      const row = await scoped(context, scope).unique()
+      if (row) await context.db.delete(row._id)
+      for (const operation of rows) await context.db.delete(operation._id)
+      return { deleted: row ? 1 : 0, retention: 'provider-live-rows-deleted', backups: 'operator-policy' }
+    }) },
+    'counter.lookup': { input: value => {
+      const input = exact(value, ['operationId'])
+      if (typeof input.operationId !== 'string' || !/^[A-Za-z0-9_-]{16,128}$/.test(input.operationId)) throw new ExtensionError('invalid-input')
+      return { operationId: input.operationId }
+    }, output: value => value === null ? null : parseProviderOperationProof(value),
+    run: ({ context, scope }, input) => lookupConvexOperation(context, scope, input.operationId) },
+  } })
+}
+export const health = internalQuery({ args: {}, handler: context => convexHealth(context, parseManifest(manifest)) })
+// This is intentionally internal. No public mutation/query exposes member tables.
+export const invoke = internalMutation({ args: { delegation: v.string(), payload: v.any() },
+  handler: (context, args) => runConvexInvocation(extension(), context, { delegation: args.delegation, payload: json(args.payload) }) })
+`,
+      'convex/http.ts': `import { httpRouter } from 'convex/server'
+import { httpAction } from './_generated/server'
+import { internal } from './_generated/api'
+import { createConvexHttpHandler, createRootAdmissionConsumer } from '@mnstry/atelier/extensions/convex'
+import { extension } from './backend'
+const http = httpRouter()
+http.route({ path: '/health', method: 'GET', handler: httpAction(async context => {
+  try { return Response.json(await context.runQuery(internal.backend.health, {}), { headers: { 'cache-control': 'no-store' } }) }
+  catch { return Response.json({ code: 'unavailable' }, { status: 503, headers: { 'cache-control': 'no-store' } }) }
+}) })
+http.route({ path: '/invoke', method: 'POST', handler: httpAction((context, request) => {
+  const consume: ReturnType<typeof createRootAdmissionConsumer> = (claims, delegation) => createRootAdmissionConsumer({
+    origin: process.env.EXTENSION_ROOT_ORIGIN ?? '', allowLocalTesting: process.env.EXTENSION_ALLOW_LOCAL_TESTING === 'true' })(claims, delegation)
+  return createConvexHttpHandler(extension(consume), args => context.runMutation(internal.backend.invoke, args))(request)
+}) })
+export default http
+`,
+      'convex/tsconfig.json': JSON.stringify({ compilerOptions: { strict: true, target: 'ES2022', lib: ['ES2022', 'DOM'],
+        module: 'ESNext', moduleResolution: 'Bundler', resolveJsonModule: true, allowJs: true, noEmit: true, skipLibCheck: true, types: ['node'] }, include: ['./**/*'], exclude: ['./_generated'] }, null, 2) + '\n',
+      'env.example': '# Set only on the customer-owned Convex deployment; public verification keys only.\nEXTENSION_ROOT_ORIGIN=\nEXTENSION_ROOT_ISSUER=\nEXTENSION_ROOT_PUBLIC_KEYS=\nEXTENSION_AUDIENCE=\nEXTENSION_INSTALLATION_ID=\n',
+      'README.md': `# Native counter extension
+
+This source-only scaffold uses Convex 1.46.0 and its native schema, indexes,
+internal mutations, OCC transactions and HTTP actions. It installs no SQL driver.
+Use your own Convex project and reviewed deployment workflow. Atelier init never
+starts a backend, logs into an account, deploys code or grants an installation.
+
+Install the exact Atelier candidate tarball and pinned dependencies. The versioned native schema lives in migrations/001-schema.ts; convex/schema.ts
+re-exports it. Its bytes are bound by the existing schema/migration digest.
+Run Convex code generation before the final seal; its generated files are sealed too.
+Run the project typecheck, then atelier extension seal, validate and bundle.
+After deployment, validate again and bind the tested deployment identity to the
+release before host registration. Generated files changing makes the seal stale.
+Set the public verification keys, Root issuer/admission origin, exact backend
+invocation audience and opaque installation reference in deployment environment.
+No admin key, Root database credential or member identity crosses this boundary.
+
+POST /invoke verifies the original short-lived delegation, consumes Root admission
+once, then calls the private internal mutation with the original token and payload.
+The mutation verifies them again. Native transactions commit custom writes and the
+indexed operation result atomically. A lost HTTP reply needs a new admitted lookup
+operation; never repeat a business write just because its reply was lost.
+
+GET /health reports the existing immutable release/schema health envelope after\nnative index checks, without member data. Output validators must preserve the\ncanonical result; construct that result inside the action before its once helper.\n\nThe sample supports scoped set/get/export/delete/lookup. Delete clears this member's
+live sample rows and older operation results atomically, up to 500 operations; a
+larger history refuses and requires a paginated erasure design. Backup retention
+remains the operator's responsibility. Existing admitted effects may finish after
+disable. No direct public query or subscription exposes member tables. Reactive
+revocation, migrations/backfills, comprehensive privacy lifecycle and complete host
+journeys remain separate qualification work. Do not enable a host profile on the
+strength of a scaffold or unit test.
+`,
+    },
+  }
+}

package/src/extensions/scaffold-sql.mjs

@@ -0,0 +1,144 @@
+// Generated projects retain the native ORM. These strings never run in Atelier.
+const drizzleSchema = `import { sql } from 'drizzle-orm'
+import { bigint, boolean, check, integer, jsonb, pgSchema, primaryKey, text } from 'drizzle-orm/pg-core'
+export const extensionData=pgSchema('extension_data')
+const scope = () => ({ installationId:text('installation_id').notNull(),tenantRef:text('tenant_ref').notNull(),subjectRef:text('subject_ref').notNull() })
+export const countersInExtensionData=extensionData.table('counters',{...scope(),value:integer('value').notNull()},table=>[
+  primaryKey({columns:[table.installationId,table.tenantRef,table.subjectRef]}),check('counter_value',sql\`\${table.value} BETWEEN 0 AND 1000000\`),
+])
+export const operationsInExtensionData=extensionData.table('operations',{...scope(),operationId:text('operation_id').notNull(),actionId:text('action_id').notNull(),
+  generation:bigint('generation',{mode:'bigint'}).notNull(),releaseDigest:text('release_digest').notNull(),payloadDigest:text('payload_digest').notNull(),
+  completed:boolean('completed').notNull().default(false),result:jsonb('result')},table=>[
+  primaryKey({columns:[table.installationId,table.tenantRef,table.subjectRef,table.operationId]}),
+  check('operation_generation',sql\`\${table.generation}>0\`),check('release_digest_format',sql\`\${table.releaseDigest} ~ '^[a-f0-9]{64}$'\`),
+  check('payload_digest_format',sql\`\${table.payloadDigest} ~ '^[a-f0-9]{64}$'\`),
+])
+`
+const prismaSchema = `generator client {
+  provider = "prisma-client"
+  output = "../src/generated/prisma"
+  moduleFormat = "esm"
+  importFileExtension = "js"
+}
+datasource db {
+  provider = "postgresql"
+  schemas = ["extension_data"]
+}
+model Counter {
+  installationId String @map("installation_id")
+  tenantRef String @map("tenant_ref")
+  subjectRef String @map("subject_ref")
+  value Int
+  @@id([installationId,tenantRef,subjectRef])
+  @@map("counters")
+  @@schema("extension_data")
+}
+model Operation {
+  installationId String @map("installation_id")
+  tenantRef String @map("tenant_ref")
+  subjectRef String @map("subject_ref")
+  operationId String @map("operation_id")
+  actionId String @map("action_id")
+  generation BigInt
+  releaseDigest String @map("release_digest")
+  payloadDigest String @map("payload_digest")
+  completed Boolean @default(false)
+  result Json?
+  @@id([installationId,tenantRef,subjectRef,operationId])
+  @@map("operations")
+  @@schema("extension_data")
+}
+`
+function replace(source, before, after) {
+  if(source.split(before).length!==2) throw new Error('scaffold source shape changed')
+  return source.replace(before,after)
+}
+export function sqlProjectFiles(profile, baseBackend, baseMigration) {
+  const drizzle=profile==='drizzle-db-first'||profile==='drizzle-code-first'
+  if(!drizzle && profile!=='prisma-7-postgres')throw new Error('unsupported SQL profile')
+  let backend=baseBackend
+  const names=drizzle?['Drizzle','drizzle']:['Prisma','prisma']
+  backend=backend.replaceAll('oncePostgresOperation',`once${names[0]}Operation`).replaceAll('lookupPostgresOperation',`lookup${names[0]}Operation`)
+    .replaceAll('withPostgresScope',`with${names[0]}Scope`).replaceAll('postgresHealth',`${names[1]}Health`)
+    .replace("from '@mnstry/atelier/extensions/postgres'",`from '@mnstry/atelier/extensions/${names[1]}'`)
+  backend=replace(backend,"import type { Sql } from 'postgres'",drizzle?`import type { Sql } from 'postgres'
+import { and, eq, sql as query } from 'drizzle-orm'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { countersInExtensionData as counters } from './${profile==='drizzle-db-first'?'introspected/':''}schema.js'
+import type { VerifiedScope } from '@mnstry/atelier/extensions/server'
+const scopedWhere=(scope:VerifiedScope)=>and(eq(counters.installationId,scope.installationId),eq(counters.tenantRef,scope.tenantRef),eq(counters.subjectRef,scope.subjectRef))`:
+`import type { PrismaClient } from './generated/prisma/client.js'`)
+  if(drizzle) {
+    backend=backend.replaceAll('database, scope, input, async sql =>','database, scope, input, query, async db =>')
+      .replaceAll('database, scope, async sql =>','database, scope, query, async db =>')
+    backend=backend.replace('const database = options.database','const database = drizzle(options.database,{schema:{counters}})').replace('lookupDrizzleOperation(database, scope, input.operationId)','lookupDrizzleOperation(database, scope, query, input.operationId)').replace('drizzleHealth(database)',`drizzleHealth(options.database,'${profile}')`)
+  }else backend=backend.replace('database: Sql','database: PrismaClient').replaceAll('database, scope, input, async sql =>','database, scope, input, async db =>').replaceAll('database, scope, async sql =>','database, scope, async db =>')
+  backend=replace(backend,`await sql\`INSERT INTO extension_data.counters (installation_id,tenant_ref,subject_ref,value)
+          VALUES (\${scope.installationId},\${scope.tenantRef},\${scope.subjectRef},\${input.value})
+          ON CONFLICT (installation_id,tenant_ref,subject_ref) DO UPDATE SET value=excluded.value\``,drizzle?
+`await db.insert(counters).values({installationId:scope.installationId,tenantRef:scope.tenantRef,subjectRef:scope.subjectRef,value:input.value})
+          .onConflictDoUpdate({target:[counters.installationId,counters.tenantRef,counters.subjectRef],set:{value:input.value}})`:
+`await db.counter.upsert({where:{installationId_tenantRef_subjectRef:{installationId:scope.installationId,tenantRef:scope.tenantRef,subjectRef:scope.subjectRef}},
+          create:{installationId:scope.installationId,tenantRef:scope.tenantRef,subjectRef:scope.subjectRef,value:input.value},update:{value:input.value}})`)
+  const read=`const [row] = await sql\`SELECT value FROM extension_data.counters WHERE installation_id=\${scope.installationId}
+          AND tenant_ref=\${scope.tenantRef} AND subject_ref=\${scope.subjectRef}\``
+  if(backend.split(read).length!==3)throw new Error('scaffold read shape changed')
+  backend=backend.replaceAll(read,drizzle?`const [row]=await db.select({value:counters.value}).from(counters).where(scopedWhere(scope)).limit(1)`:
+`const row=await db.counter.findUnique({where:{installationId_tenantRef_subjectRef:{installationId:scope.installationId,tenantRef:scope.tenantRef,subjectRef:scope.subjectRef}}})`)
+  backend=replace(backend,`const rows = await sql\`DELETE FROM extension_data.counters WHERE installation_id=\${scope.installationId}
+          AND tenant_ref=\${scope.tenantRef} AND subject_ref=\${scope.subjectRef} RETURNING value\``,drizzle?
+`const rows=await db.delete(counters).where(scopedWhere(scope)).returning({value:counters.value})`:
+`const deleted=await db.counter.deleteMany({where:{installationId:scope.installationId,tenantRef:scope.tenantRef,subjectRef:scope.subjectRef}})
+        const rows=Array.from({length:deleted.count})`)
+  backend=replace(backend,`await sql\`DELETE FROM extension_data.operations WHERE installation_id=\${scope.installationId}
+          AND tenant_ref=\${scope.tenantRef} AND subject_ref=\${scope.subjectRef} AND operation_id<>\${scope.operationId}\``,drizzle?
+`await db.execute(query\`DELETE FROM extension_data.operations WHERE installation_id=\${scope.installationId}
+          AND tenant_ref=\${scope.tenantRef} AND subject_ref=\${scope.subjectRef} AND operation_id<>\${scope.operationId}\`)`:
+`await db.$executeRaw\`DELETE FROM extension_data.operations WHERE installation_id=\${scope.installationId}
+          AND tenant_ref=\${scope.tenantRef} AND subject_ref=\${scope.subjectRef} AND operation_id<>\${scope.operationId}\``)
+  const files={'src/backend.ts':backend}
+  const dependencies=drizzle?{'drizzle-orm':'0.44.5',postgres:'3.4.7'}:{'@prisma/client':'7.10.0','@prisma/adapter-pg':'7.10.0',pg:'8.16.3'}
+  const devDependencies=drizzle?{'drizzle-kit':'0.31.8'}:{prisma:'7.10.0','@types/pg':'8.15.5'}
+  const scripts=drizzle?{'schema:generate':'drizzle-kit generate --config drizzle.config.ts','schema:introspect':'drizzle-kit pull --config drizzle-introspect.config.ts && node src/normalize-introspection.mjs'}:
+    {'schema:generate':'prisma generate','schema:introspect':'prisma db pull'}
+  if(drizzle){
+    // Drizzle Kit 0.31 emits an extensionless local relation import. Preserve
+    // the native generated schema and normalize only that Node ESM specifier.
+    files['src/normalize-introspection.mjs']=`import {lstat,readFile,rename,rm,writeFile} from 'node:fs/promises'
+import {randomUUID} from 'node:crypto'
+const file=new URL('./introspected/relations.ts',import.meta.url)
+const identity=await lstat(file)
+if(!identity.isFile()||identity.isSymbolicLink())throw new Error('Generated relations must be a regular file')
+const before=await readFile(file,'utf8')
+const after=before.replaceAll('from "./schema"','from "./schema.js"').replaceAll("from './schema'","from './schema.js'")
+if(after!==before){
+  const temporary=new URL('./introspected/.relations-'+randomUUID()+'.tmp',import.meta.url)
+  try {
+    await writeFile(temporary,after,{flag:'wx'})
+    const current=await lstat(file)
+    if(!current.isFile()||current.isSymbolicLink()||current.dev!==identity.dev||current.ino!==identity.ino||await readFile(file,'utf8')!==before)throw new Error('Generated relations changed concurrently')
+    await rename(temporary,file)
+  } finally { await rm(temporary,{force:true}) }
+}
+`
+    files[`src/${profile==='drizzle-db-first'?'introspected/':''}schema.ts`]=drizzleSchema
+    files['drizzle.config.ts']=`import {defineConfig} from 'drizzle-kit'\nexport default defineConfig({dialect:'postgresql',schema:'./src/${profile==='drizzle-db-first'?'introspected/':''}schema.ts',out:'./migrations/drizzle',schemaFilter:['extension_data'],strict:true,verbose:false})\n`
+    files['drizzle-introspect.config.ts']=`import {defineConfig} from 'drizzle-kit'\nconst url=process.env.EXTENSION_MIGRATION_DATABASE_URL\nif(!url)throw new Error('Migration database secret must be supplied explicitly')\nexport default defineConfig({dialect:'postgresql',out:'./src/introspected',schemaFilter:['extension_data'],dbCredentials:{url},strict:true,verbose:false})\n`
+    if(profile==='drizzle-code-first') {
+      // The native generator creates tables. These reviewed policy statements must follow it.
+      files['migrations/001-initial.sql']=`-- Apply the native Drizzle-generated SQL first, then migrations/002-governance.sql.\n`
+      const governance=baseMigration.split('\n').filter(line=>/^(REVOKE|ALTER TABLE|CREATE POLICY|  USING|    AND subject_ref|  WITH CHECK|GRANT)/.test(line))
+      files['migrations/002-governance.sql']=governance.join('\n')+'\n'
+    }
+  } else {
+    files['prisma/schema.prisma']=prismaSchema
+    files['prisma.config.ts']=`import {defineConfig} from 'prisma/config'\nconst url=process.env.EXTENSION_MIGRATION_DATABASE_URL\nexport default defineConfig({schema:'prisma/schema.prisma',...(url?{datasource:{url}}:{})})\n`
+    files['src/database.ts']=`import {PrismaPg} from '@prisma/adapter-pg'\nimport {PrismaClient} from './generated/prisma/client.js'\nexport function createDatabase(connectionString:string){\n  if(!connectionString)throw new Error('Application database secret must be supplied explicitly')\n  return new PrismaClient({adapter:new PrismaPg({connectionString,max:6,connectionTimeoutMillis:5000,idleTimeoutMillis:1000},{schema:'extension_data'})})\n}\n`
+  }
+  files['env.example']='# Keep both secrets outside source; use separate restricted application and migration roles.\nEXTENSION_DATABASE_URL=\nEXTENSION_MIGRATION_DATABASE_URL=\n'
+  const instructions=drizzle?(profile==='drizzle-code-first'?
+    'This profile uses native Drizzle code-first generation. After npm install, run npm run schema:generate, review its SQL under migrations/drizzle, apply it with the separate migration role, then apply migrations/002-governance.sql. Omitting forced RLS makes health refuse. Reseal after generator output changes. Later generation is a proposed migration; review it before application.':
+    'This profile uses database-first ownership. Apply the reviewed baseline migration with the migration role, then run npm run schema:introspect against only extension_data. Review src/introspected/schema.ts and retain it in source; it replaces the initial example projection. The backend consumes that actual generated schema. Reseal after introspection. Introspection does not prove RLS policy semantics.'):
+    'This profile uses Prisma 7 with its native pg adapter and generated client. After npm install, run npm run schema:generate. Apply migrations/001-initial.sql with the separate migration role. Prisma schema/client generation does not install RLS; the reviewed SQL is required. Use src/database.ts from your own host with an explicit application secret. Reseal after schema/client changes. Prisma 8 remains an unqualified separate experiment.'
+  return {files,dependencies,devDependencies,scripts,instructions}
+}

package/src/extensions/server.d.mts

@@ -0,0 +1,20 @@
+import type { KeyObject } from 'node:crypto'
+import type { ExtensionManifest, Json } from './contracts.mjs'
+export interface VerifiedScope {
+  readonly installationId: string; readonly tenantRef: string; readonly subjectRef: string; readonly generation: string;
+  readonly releaseDigest: string; readonly actionId: string; readonly operationId: string; readonly payloadDigest: string; readonly rootWrites: readonly string[];
+}
+export interface VerifierOptions {
+  issuer: string; audience: string; installationId: string; releaseDigest: string; keys: ReadonlyMap<string, KeyObject>;
+  now?: () => number; consume(claims: Readonly<Record<string, unknown>>, delegation: string): Promise<boolean>;
+}
+export interface ActionDefinition<I = Json, O = Json> {
+  input(value: unknown): I; output(value: unknown): O; run(context: { scope: VerifiedScope; signal: AbortSignal }, input: I): unknown | Promise<unknown>;
+}
+export function digest(value: unknown): string
+export function releaseDigest(value: unknown): string
+export function assertVerifiedScope(scope: VerifiedScope): void
+export function createRootAdmissionConsumer(options: { origin: string; allowLocalTesting?: boolean; fetch?: typeof fetch }): VerifierOptions['consume']
+export function defineAction<I, O>(definition: ActionDefinition<I, O>): Readonly<ActionDefinition<I, O>>
+export function defineExtension(options: { manifest: ExtensionManifest; verifier: VerifierOptions; actions: Record<string, ActionDefinition<any, any>> }): unknown
+export function createExtensionHandler(extension: ReturnType<typeof defineExtension>): (request: Request) => Promise<Response>

package/src/extensions/server.mjs

@@ -0,0 +1,102 @@
+import { createHash, verify } from 'node:crypto'
+import { canonicalJson, ExtensionError, parseManifest } from './contracts.mjs'
+import { assertDelegationBinding, decodeDelegation, unauthorized, validateDelegationClaims } from './delegation.mjs'
+export { createRootAdmissionConsumer } from './admission.mjs'
+
+export const digest = value => createHash('sha256').update(canonicalJson(value)).digest('hex')
+export function releaseDigest(value) {
+  const { releaseDigest: omitted, ...rest } = parseManifest(value)
+  return digest(rest)
+}
+const admittedScopes = new WeakMap()
+const extensionDefinitions = new WeakMap()
+function freezeJson(value) {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freezeJson); Object.freeze(value) }
+  return value
+}
+export function assertVerifiedScope(scope) {
+  if (!scope || !admittedScopes.get(scope)?.()) throw new ExtensionError('unauthorized', 401)
+}
+function verifiedClaims(delegation, options) {
+  try {
+    const decoded = decodeDelegation(delegation)
+    const key = options.keys.get(decoded.header.kid)
+    if (!key || key.type !== 'public' || key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1' ||
+        !verify('sha256', decoded.signed, { key, dsaEncoding: 'ieee-p1363' }, decoded.signature)) return unauthorized()
+    return validateDelegationClaims(decoded.claims, options)
+  } catch { return unauthorized() }
+}
+export function defineAction(definition) {
+  if (!definition || ['input', 'output', 'run'].some(key => typeof definition[key] !== 'function')) throw new ExtensionError('invalid-input')
+  return Object.freeze({ input: definition.input, output: definition.output, run: definition.run })
+}
+export function defineExtension({ manifest, verifier, actions }) {
+  const pinned = parseManifest(manifest)
+  if (pinned.releaseDigest !== releaseDigest(pinned) || pinned.actions.some(action => !Object.hasOwn(actions,action.id)) ||
+      Object.keys(actions).some(id => !pinned.actions.some(action => action.id === id)) || typeof verifier.consume !== 'function') throw new ExtensionError('invalid-input')
+  const runtime = Object.freeze({ manifest: freezeJson(pinned), verifier: Object.freeze({ ...verifier, keys: new Map(verifier.keys) }),
+    actions: Object.freeze(Object.fromEntries(Object.entries(actions).map(([id, action]) => [id, defineAction(action)]))) })
+  const handle = Object.freeze({ manifest: runtime.manifest })
+  extensionDefinitions.set(handle, runtime)
+  return handle
+}
+export function createExtensionHandler(handle) {
+  const extension = extensionDefinitions.get(handle)
+  if (!extension) throw new ExtensionError('invalid-input')
+  return async request => {
+    let admitted = false
+    try {
+      if (request.method !== 'POST' || request.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json') return new Response(null, { status: 415 })
+      const delegation = request.headers.get('authorization')?.match(/^Bearer ([A-Za-z0-9_.-]+)$/)?.[1]
+      if (!delegation) return unauthorized()
+      const claims = verifiedClaims(delegation, extension.verifier)
+      const manifest = extension.manifest
+      assertDelegationBinding(claims, manifest, extension.verifier)
+      const declared = manifest.actions.find(action => action.id === claims.actionId)
+      const action = Object.hasOwn(extension.actions,claims.actionId) ? extension.actions[claims.actionId] : null
+      if (!declared || !action) return unauthorized()
+      const body = request.body?.getReader()
+      if (!body) throw new ExtensionError('invalid-input')
+      let input
+      try {
+        let size = 0
+        const chunks = []
+        for (;;) {
+          const { value, done } = await body.read()
+          if (done) break
+          size += value.byteLength
+          if (size > 65536) throw new ExtensionError('invalid-input')
+          chunks.push(value)
+        }
+        input = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+      } finally { await body.cancel().catch(() => {}) }
+      if (digest(input) !== claims.payloadDigest) throw new ExtensionError('invalid-input')
+      input = action.input(input)
+      if (digest(input) !== claims.payloadDigest) throw new ExtensionError('invalid-input')
+      if (!await extension.verifier.consume(claims, delegation)) throw new ExtensionError('forbidden', 403)
+      admitted = true
+      const scope = Object.freeze({ installationId: claims.installationId, generation: claims.generation, releaseDigest: claims.releaseDigest,
+        operationId: claims.operationId, actionId: claims.actionId, payloadDigest: claims.payloadDigest,
+        tenantRef: claims.tenantRef, subjectRef: claims.subjectRef, rootWrites: claims.rootWrites })
+      const deadline = Math.min(claims.exp * 1000, (extension.verifier.now?.() ?? Date.now()) + declared.timeoutMs)
+      const controller = new AbortController()
+      admittedScopes.set(scope, () => !controller.signal.aborted && deadline > (extension.verifier.now?.() ?? Date.now()))
+      let expire
+      const expired = new Promise((_, reject) => { expire = () => { const error = new ExtensionError('operation-unknown', 409); controller.abort(error); reject(error) } })
+      const timer = setTimeout(expire, Math.max(0, deadline - (extension.verifier.now?.() ?? Date.now())))
+      let result
+      try {
+        if (deadline <= (extension.verifier.now?.() ?? Date.now())) throw new ExtensionError('operation-unknown', 409)
+        result = action.output(await Promise.race([Promise.resolve().then(() => action.run({ scope, signal: controller.signal }, input)), expired]))
+        if (controller.signal.aborted || deadline <= (extension.verifier.now?.() ?? Date.now())) throw new ExtensionError('operation-unknown', 409)
+      } finally { clearTimeout(timer); admittedScopes.delete(scope) }
+      if (Buffer.byteLength(canonicalJson(result)) > 65536) throw new ExtensionError('operation-unknown', 409)
+      return Response.json({ operationId: claims.operationId, state: 'succeeded', result, resultDigest: digest(result) }, { headers: { 'cache-control': 'no-store' } })
+    } catch (error) {
+      const statuses = { 'invalid-input': 400, unauthorized: 401, forbidden: 403, 'operation-unknown': 409, unavailable: 503 }
+      const code = admitted ? 'operation-unknown' : error instanceof ExtensionError && Object.hasOwn(statuses, error.code) ? error.code : 'unavailable'
+      return Response.json({ code }, { status: statuses[code],
+        headers: { 'cache-control': 'no-store' } })
+    }
+  }
+}

package/src/extensions/sql-scope.mjs

@@ -0,0 +1,22 @@
+import { canonicalJson, ExtensionError, text } from './contracts.mjs'
+
+export async function assertApplicationRole(sql) {
+  const [role] = await sql`SELECT r.rolsuper, r.rolbypassrls,
+    EXISTS (SELECT 1 FROM pg_roles parent WHERE pg_has_role(r.oid,parent.oid,'MEMBER')
+      AND (parent.rolsuper OR parent.rolbypassrls)) AS unsafe_membership,
+    EXISTS (SELECT 1 FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace
+      WHERE n.nspname='extension_data' AND c.relkind IN ('r','p')
+        AND (pg_has_role(r.oid,c.relowner,'MEMBER') OR NOT c.relrowsecurity OR NOT c.relforcerowsecurity)) AS unsafe_tables
+    FROM pg_roles r WHERE r.rolname=current_user`
+  if (!role || role.rolsuper !== false || role.rolbypassrls !== false || role.unsafe_membership !== false || role.unsafe_tables !== false) throw new ExtensionError('forbidden', 403)
+}
+
+export function boundedSqlResult(value) {
+  const encoded=canonicalJson(value)
+  if(Buffer.byteLength(encoded)>60*1024)throw new ExtensionError('invalid-input')
+  return JSON.parse(encoded)
+}
+
+export function assertSqlOperationId(value) {
+  if(!/^[A-Za-z0-9_-]{16,128}$/.test(text(value)))throw new ExtensionError('invalid-input')
+}

package/src/graph/graph.mjs

@@ -5,9 +5,10 @@ import { VALID_AUDIENCES as PROJECTION_AUDIENCES } from '../projection/policy.mj
 import {
   REPO_ACCESS_SCHEMA,
   VALID_RELATION_TYPES,
-  buildKnowledgeGraph,
+  buildKnowledgeGraphSteps,
   createGraphFileCache,
   parseYamlSubset,
+  runGraphSteps,
 } from './knowledge-graph.mjs'
 
 export { createGraphFileCache }
@@ -116,11 +117,12 @@ function externalRepos(project) {
     .sort((a, b) => String(a.name).localeCompare(String(b.name)))
 }
 
-function canonicalBuild(project, overrides = {}) {
+function* canonicalBuildSteps(project, overrides = {}) {
   const input = canonicalInput(project)
-  const result = buildKnowledgeGraph({ ...input.options, ...overrides })
+  const result = yield* buildKnowledgeGraphSteps({ ...input.options, ...overrides })
   return { input, result }
 }
+const canonicalBuild = (project, overrides = {}) => runGraphSteps(canonicalBuildSteps(project, overrides))
 
 // The supported project-to-options seam: the exact buildKnowledgeGraph options
 // every graph consumer derives from a loaded project, plus the configured
@@ -144,8 +146,14 @@ const canonicalEdgeId = (edge) => JSON.stringify([edge.source, edge.type, edge.t
 // bytes did not change; the result is the same as without it. `observedDigest`
 // (see createGraphFileCache) lets a caller that observes sources by digest
 // spare the read of a source it knows unchanged.
-export function buildCanonicalGraph(project, { isLinkTargetEligible, isAssetEligible, fileCache = null, observedDigest = null } = {}) {
-  const { input, result } = canonicalBuild(project, {
+// buildCanonicalGraphSteps is the same build as steps (see buildKnowledgeGraphSteps), for a caller that waits between
+// them; buildCanonicalGraph runs them through.
+export function buildCanonicalGraph(project, options = {}) {
+  return runGraphSteps(buildCanonicalGraphSteps(project, options))
+}
+
+export function* buildCanonicalGraphSteps(project, { isLinkTargetEligible, isAssetEligible, fileCache = null, observedDigest = null } = {}) {
+  const { input, result } = yield* canonicalBuildSteps(project, {
     ...(isLinkTargetEligible ? { isLinkTargetEligible } : {}),
     ...(isAssetEligible ? { isAssetEligible } : {}),
     ...(fileCache ? { fileCache } : {}),

package/src/graph/knowledge-graph.mjs

@@ -1054,7 +1054,7 @@ export function resolveWorkspaceLinks({ repos = [], isLinkTargetEligible = () =>
 
   for (const repo of enrolled) {
     for (const [rel, node] of repo.nodesByPath) {
-      if (!rel.endsWith('.md') || !isLinkTargetEligible(node)) continue
+      if (!isMarkdownPath(rel) || !isLinkTargetEligible(node)) continue
       const { occurrences, utf8Exact } = scanned?.get(node) ?? scanMarkdownSource(fs.readFileSync(path.join(repo.root, rel)))
       const finding = (code, occurrence, detail, extra = {}) =>
         diagnostics.push({
@@ -1387,7 +1387,24 @@ function markdownCensus({ repoName, repoRoot, coverage, file, accessConfig, cach
   return { node: structuredClone(entry.node), scan: structuredClone(entry.scan), reused: entry === cached, read }
 }
 
-export function buildKnowledgeGraph({
+// Runs the steps of a graph build through, with no wait, and answers what the build answers.
+export function runGraphSteps(steps) {
+  for (;;) {
+    const step = steps.next()
+    if (step.done) return step.value
+  }
+}
+
+// The knowledge graph of a workspace, in one stretch. Every caller but the maintenance engine's tick builds it this way.
+export function buildKnowledgeGraph(options) {
+  return runGraphSteps(buildKnowledgeGraphSteps(options))
+}
+
+// The same build as steps: one after each Markdown source of the census (its read, hash and parse, or its reuse from
+// the file cache), named 'graph-census'. A caller that gives the event loop a turn between steps (the maintenance
+// engine) keeps a large census from holding it; walking the directories, resolving links and assembling the graph
+// are not split. The answer is the one buildKnowledgeGraph gives.
+export function* buildKnowledgeGraphSteps({
   workspaceRoot,
   repoAccessConfig,
   repoRoots = null,
@@ -1466,6 +1483,7 @@ export function buildKnowledgeGraph({
         scanned.set(node, entry.scan)
         reuse[entry.reused ? 'reused' : 'derived'] += 1
         if (entry.read) reuse.read += 1
+        yield 'graph-census'
       } else {
         node = nodeForFile(repoName, repoRoot, coverage, file, accessConfig)
       }