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

package/src/extensions/client.mjs

@@ -0,0 +1,99 @@
+import { canonicalJson, exact, ExtensionError, parseInstallationBinding, parseManifest, parseOperationReceipt, parseReleaseBundle, text } from './contracts.mjs'
+
+const opaque = value => { if (!/^[A-Za-z0-9_-]{16,128}$/.test(text(value))) throw new ExtensionError('invalid-input'); return value }
+const actionIdValue = value => { if (!/^[a-z0-9][a-z0-9._-]{2,127}$/.test(text(value)) || /^(?:lifecycle|installation|extension)\./.test(value)) throw new ExtensionError('invalid-input'); return value }
+const codes = new Set(['invalid-input', 'unauthorized', 'forbidden', 'stale-installation', 'disabled', 'idempotency-conflict', 'operation-unknown', 'release-conflict', 'unavailable'])
+const registration = (value, releaseDigest) => {
+  const result=exact(JSON.parse(canonicalJson(value)),['releaseId','releaseDigest'])
+  if(result.releaseDigest!==releaseDigest)throw new ExtensionError('unavailable',503)
+  return {releaseId:opaque(result.releaseId),releaseDigest:result.releaseDigest}
+}
+// The caller supplies an authenticated host fetch; destinations and credentials are host-owned.
+export function createHttpHostTransport(hostFetch) {
+  if (typeof hostFetch !== 'function') throw new ExtensionError('invalid-input')
+  const base = '/api/root-runtime/extensions'
+  const segment = value => encodeURIComponent(opaque(value))
+  async function send(path, body) {
+    const response = await hostFetch(`${base}${path}`, { method: body === undefined ? 'GET' : 'POST',
+      credentials: 'same-origin', cache: 'no-store', redirect: 'error',
+      ...(body === undefined ? {} : { headers: { 'content-type': 'application/json' }, body: canonicalJson(body) }) })
+    let value
+    const reader = response.body?.getReader()
+    if (!reader) throw new ExtensionError('unavailable', 503)
+    try {
+      const chunks = []; let size = 0
+      for (;;) {
+        const part = await reader.read()
+        if (part.done) break
+        size += part.value.byteLength
+        if (size > 131072) throw new ExtensionError('unavailable', 503)
+        chunks.push(part.value)
+      }
+      const bytes = new Uint8Array(size); let offset = 0
+      for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength }
+      value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+    } catch { throw new ExtensionError('unavailable', 503) } finally { await reader.cancel().catch(() => {}) }
+    if (!response.ok) throw new ExtensionError(codes.has(value?.code) ? value.code : 'unavailable', response.status)
+    return value
+  }
+  const installation = id => `/installations/${segment(id)}`
+  return Object.freeze({
+    registerRelease: async input => {
+      const bundle=parseReleaseBundle(input), expectedReleaseDigest=bundle.manifest.releaseDigest
+      return registration(await send('/releases',bundle),expectedReleaseDigest)
+    },
+    getInstallation: async id => parseInstallationBinding(await send(installation(id))),
+    invoke: async request => {
+      const { installationId, actionId, ...body } = request
+      return parseOperationReceipt(await send(`${installation(installationId)}/actions/${encodeURIComponent(actionIdValue(actionId))}`, body))
+    },
+    lookupOperation: async (id, idempotencyKey, actionId) => {
+      const value = await send(`${installation(id)}/lookup`, { idempotencyKey, actionId })
+      return value === null ? null : parseOperationReceipt(value)
+    },
+    recoverOperation: async ({ installationId, ...binding }, idempotencyKey, actionId) =>
+      parseOperationReceipt(await send(`${installation(installationId)}/recover`, { ...binding, idempotencyKey, actionId })),
+    recordResult: async operationId => {
+      const value = exact(await send(`/operations/${segment(operationId)}/result`, {}), ['recorded'])
+      if (value.recorded !== true) throw new ExtensionError('unavailable', 503)
+    },
+    configure: async (manifest, connectionRef, environment) => parseInstallationBinding(await send('/installations', { manifest, connectionRef, environment })),
+    transition: async ({ installationId, ...binding }, transition) => parseInstallationBinding(await send(`${installation(installationId)}/lifecycle`, { ...binding, transition })),
+    upgrade: async ({ installationId, ...binding }, manifest) => parseInstallationBinding(await send(`${installation(installationId)}/upgrade`, { ...binding, manifest })),
+  })
+}
+export function createExtensionClient(transport) {
+  return Object.freeze({
+    getInstallation: async id => parseInstallationBinding(await transport.getInstallation(opaque(id))),
+    invoke: async (binding, actionId, input, idempotencyKey) => parseOperationReceipt(await transport.invoke({
+      ...parseInstallationBinding(binding), actionId: actionIdValue(actionId), idempotencyKey: text(idempotencyKey), input: JSON.parse(canonicalJson(input)),
+    })),
+    lookupOperation: async (id, key, action) => {
+      const result = await transport.lookupOperation(opaque(id), text(key), actionIdValue(action))
+      return result === null ? null : parseOperationReceipt(result)
+    },
+    recoverOperation: async (binding, key, action) => parseOperationReceipt(await transport.recoverOperation(parseInstallationBinding(binding), text(key), actionIdValue(action))),
+    recordResult: async id => {
+      if (!/^[A-Za-z0-9_-]{16,128}$/.test(text(id))) throw new ExtensionError('invalid-input')
+      await transport.recordResult(id)
+    },
+  })
+}
+export function createExtensionAdminClient(transport) {
+  return Object.freeze({
+    registerRelease: async value => {
+      if(typeof transport.registerRelease!=='function')throw new ExtensionError('unavailable',503)
+      const bundle=parseReleaseBundle(value), expectedReleaseDigest=bundle.manifest.releaseDigest
+      return registration(await transport.registerRelease(bundle),expectedReleaseDigest)
+    },
+    configure: async (manifest, connectionRef, environment = 'development') => {
+      if (!['development', 'staging', 'production'].includes(environment)) throw new ExtensionError('invalid-input')
+      return parseInstallationBinding(await transport.configure(parseManifest(manifest), text(connectionRef), environment))
+    },
+    transition: async (binding, transition) => {
+      if (!['verify', 'enable', 'disable', 'remove'].includes(transition)) throw new ExtensionError('invalid-input')
+      return parseInstallationBinding(await transport.transition(parseInstallationBinding(binding), transition))
+    },
+    upgrade: async (binding, manifest) => parseInstallationBinding(await transport.upgrade(parseInstallationBinding(binding), parseManifest(manifest))),
+  })
+}

package/src/extensions/contracts.d.mts

@@ -0,0 +1,29 @@
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json }
+export interface InstallationBinding { installationId: string; generation: string; releaseDigest: string }
+export interface Invocation extends InstallationBinding { actionId: string; idempotencyKey: string; input: Json }
+export interface OperationReceipt { operationId: string; state: 'pending' | 'admitted' | 'succeeded' | 'unknown' | 'failed'; result?: Json; resultDigest?: string }
+export interface ReservedExtensionFields { ext?: Record<string, never> }
+export interface ActionManifest extends ReservedExtensionFields { id: string; effect: 'read' | 'write'; scope: 'member' | 'tenant'; inputSchemaRef: string; outputSchemaRef: string; timeoutMs: number }
+export interface ExtensionManifest extends ReservedExtensionFields {
+  contractVersion?: string;
+  schema: 'mnstry.extension-manifest/v1'; extensionId: string; releaseVersion: string; releaseDigest: string; protocol: 'mnstry.extension/v1';
+  compatibility: ReservedExtensionFields & { sdkMajor: 1; rootContracts: string[]; hosts: ('web' | 'native')[] };
+  deployment: ReservedExtensionFields & { profile: 'postgres-sql' | 'drizzle-db-first' | 'drizzle-code-first' | 'prisma-7-postgres' | 'prisma-8-postgres-experimental' | 'convex-native'; bundleDigest: string; schemaDigest: string }; actions: ActionManifest[];
+  recovery?: ReservedExtensionFields & { lookupActionId: string }; permissions: ReservedExtensionFields & { rootReads: string[]; rootWrites: string[]; egress: string[] };
+  surfaces: (ReservedExtensionFields & { id: string; compositionDigest: string; actionIds: string[] })[];
+  data: ReservedExtensionFields & { classes: string[]; retention: 'until-user-delete'; exportVersion: 1; schemaVersion: string; readableSchemaVersions: string[] }
+}
+export class ExtensionError extends Error { readonly code: string; readonly status: number; constructor(code: string, status?: number) }
+export function canonicalJson(value: unknown): string
+export function text(value: unknown, limit?: number): string
+export function exact(value: unknown, required: string[], optional?: string[]): Record<string, unknown>
+export function parseManifest(value: unknown): ExtensionManifest
+export function parseInstallationBinding(value: unknown): InstallationBinding
+export function parseOperationReceipt(value: unknown): OperationReceipt
+
+export interface ProviderOperationProof extends InstallationBinding { schema: 'mnstry.extension-provider-operation/v1'; operationId: string; actionId: string; payloadDigest: string; resultDigest: string; result: Json }
+export function parseProviderOperationProof(value: unknown): ProviderOperationProof
+
+export interface ExtensionReleaseBundle { manifest: ExtensionManifest; schemaFiles: Record<string, string>; migrationDigests: Record<string, string> }
+export interface ExtensionReleaseRegistration { releaseId: string; releaseDigest: string }
+export function parseReleaseBundle(value: unknown): ExtensionReleaseBundle

package/src/extensions/contracts.mjs

@@ -0,0 +1,163 @@
+// Portable wire contracts. Host authentication and persistence stay with the consumer.
+export class ExtensionError extends Error {
+  constructor(code, status = 400) { super(code); this.name = 'ExtensionError'; this.code = code; this.status = status }
+}
+const reject = () => { throw new ExtensionError('invalid-input') }
+export function canonicalJson(value) {
+  const seen = new Set()
+  function visit(item, depth) {
+    if (depth > 16) return reject()
+    if (item === null || typeof item === 'boolean') return JSON.stringify(item)
+    if (typeof item === 'number') return Number.isFinite(item) ? JSON.stringify(item) : reject()
+    if (typeof item === 'string') {
+      for (let n = 0; n < item.length; n++) {
+        const c = item.charCodeAt(n)
+        if (c >= 0xd800 && c <= 0xdbff) {
+          const next = item.charCodeAt(++n)
+          if (!(next >= 0xdc00 && next <= 0xdfff)) return reject()
+        } else if (c >= 0xdc00 && c <= 0xdfff) return reject()
+      }
+      return JSON.stringify(item)
+    }
+    if (!item || typeof item !== 'object' || seen.has(item)) return reject()
+    seen.add(item)
+    let result
+    if (Array.isArray(item)) {
+      if (Reflect.ownKeys(item).length !== item.length + 1 || Array.from({ length: item.length }, (_, i) => i).some(i => !Object.hasOwn(item, i) || !Object.hasOwn(Object.getOwnPropertyDescriptor(item, String(i)), 'value'))) return reject()
+      result = `[${item.map(x => visit(x, depth + 1)).join(',')}]`
+    } else {
+      if (Object.getPrototypeOf(item) !== Object.prototype || Reflect.ownKeys(item).some(k => typeof k !== 'string')) return reject()
+      const keys = Reflect.ownKeys(item).sort()
+      if (keys.some(k => !Object.getOwnPropertyDescriptor(item, k).enumerable)) return reject()
+      if (keys.some(k => !Object.hasOwn(Object.getOwnPropertyDescriptor(item, k), 'value'))) return reject()
+      result = `{${keys.map(k => `${visit(k, depth + 1)}:${visit(item[k], depth + 1)}`).join(',')}}`
+    }
+    seen.delete(item)
+    return result
+  }
+  const encoded = visit(value, 0)
+  if (new TextEncoder().encode(encoded).length > 131072) return reject()
+  return encoded
+}
+export function text(value, limit = 128) {
+  if (typeof value !== 'string' || !value.length || [...value].length > limit || /[\u0000-\u001f]/u.test(value)) return reject()
+  canonicalJson(value)
+  return value
+}
+export function exact(value, required, optional = []) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype ||
+      required.some(k => !Object.hasOwn(value, k)) || Object.keys(value).some(k => !required.includes(k) && !optional.includes(k))) return reject()
+  return value
+}
+const digest = value => /^[a-f0-9]{64}$/.test(text(value, 64)) ? value : reject()
+const strings = (value, max = 64) => {
+  if (!Array.isArray(value) || value.length > max || value.some(x => typeof x !== 'string') || new Set(value).size !== value.length) return reject()
+  return value.map(x => text(x, 256))
+}
+const schemaRef = value => {
+  text(value, 256)
+  if (!/^schemas\/[a-zA-Z0-9._-]+\.json$/.test(value) || value.startsWith('/') || value.split('/').some(x => !x || x === '.' || x === '..')) return reject()
+  return value
+}
+function manifestObject(value, required, optional = []) {
+  exact(value, required, [...optional, 'ext'])
+  if (value.ext !== undefined) exact(value.ext, [])
+}
+export function parseManifest(value) {
+  const m = JSON.parse(canonicalJson(value))
+  manifestObject(m, ['schema', 'extensionId', 'releaseVersion', 'releaseDigest', 'protocol', 'compatibility', 'deployment', 'actions', 'permissions', 'surfaces', 'data'], ['recovery', 'contractVersion'])
+  if (m.contractVersion !== undefined && !/^1\.[0-9]+\.[0-9]+$/.test(text(m.contractVersion))) return reject()
+  if (m.schema !== 'mnstry.extension-manifest/v1' || m.protocol !== 'mnstry.extension/v1' ||
+      !/^[a-z0-9][a-z0-9._-]{2,127}$/.test(text(m.extensionId)) ||
+      !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(text(m.releaseVersion))) return reject()
+  const prerelease = m.releaseVersion.split('+')[0].split('-').slice(1).join('-')
+  if (prerelease.split('.').some(part => /^0\d+$/.test(part))) return reject()
+  digest(m.releaseDigest)
+  manifestObject(m.compatibility, ['sdkMajor', 'rootContracts', 'hosts'])
+  if (m.compatibility.sdkMajor !== 1 || !m.compatibility.hosts.length || strings(m.compatibility.hosts).some(x => !['web', 'native'].includes(x))) return reject()
+  strings(m.compatibility.rootContracts)
+  manifestObject(m.deployment, ['profile', 'bundleDigest', 'schemaDigest'])
+  if (!['postgres-sql', 'drizzle-db-first', 'drizzle-code-first', 'prisma-7-postgres', 'prisma-8-postgres-experimental', 'convex-native'].includes(text(m.deployment.profile))) return reject()
+  digest(m.deployment.bundleDigest); digest(m.deployment.schemaDigest)
+  if (!Array.isArray(m.actions) || !m.actions.length || m.actions.length > 64) return reject()
+  const actions = new Map()
+  for (const action of m.actions) {
+    manifestObject(action, ['id', 'effect', 'scope', 'inputSchemaRef', 'outputSchemaRef', 'timeoutMs'])
+    text(action.id)
+    if (!/^[a-z0-9][a-z0-9._-]{2,127}$/.test(action.id) || actions.has(action.id) || /^(?:lifecycle|installation|extension)\./.test(action.id) ||
+        !['read', 'write'].includes(action.effect) || !['member', 'tenant'].includes(action.scope) ||
+        !Number.isInteger(action.timeoutMs) || action.timeoutMs < 1 || action.timeoutMs > 30000) return reject()
+    schemaRef(action.inputSchemaRef); schemaRef(action.outputSchemaRef); actions.set(action.id, action)
+  }
+  if (m.recovery !== undefined) {
+    manifestObject(m.recovery, ['lookupActionId'])
+    const action = actions.get(m.recovery.lookupActionId)
+    if (!action || action.effect !== 'read' || action.scope !== 'member') return reject()
+  }
+  manifestObject(m.permissions, ['rootReads', 'rootWrites', 'egress'])
+  for (const key of ['rootReads', 'rootWrites', 'egress']) strings(m.permissions[key])
+  if (!Array.isArray(m.surfaces) || m.surfaces.length > 32) return reject()
+  const surfaces = new Set()
+  for (const surface of m.surfaces) {
+    manifestObject(surface, ['id', 'compositionDigest', 'actionIds']); text(surface.id); digest(surface.compositionDigest)
+    if (!/^[a-z0-9][a-z0-9._-]{2,127}$/.test(surface.id) || surfaces.has(surface.id) || strings(surface.actionIds).some(id => !actions.has(id))) return reject()
+    surfaces.add(surface.id)
+  }
+  manifestObject(m.data, ['classes', 'retention', 'exportVersion', 'schemaVersion', 'readableSchemaVersions'])
+  strings(m.data.classes); text(m.data.schemaVersion)
+  if (m.data.retention !== 'until-user-delete' || m.data.exportVersion !== 1 ||
+      !strings(m.data.readableSchemaVersions).includes(m.data.schemaVersion)) return reject()
+  return m
+}
+export function parseInstallationBinding(value) {
+  value = JSON.parse(canonicalJson(value))
+  exact(value, ['installationId', 'generation', 'releaseDigest'])
+  if (!/^[A-Za-z0-9_-]{16,128}$/.test(text(value.installationId)) ||
+      !/^[1-9][0-9]{0,18}$/.test(text(value.generation)) || BigInt(value.generation) > 9223372036854775807n) return reject()
+  digest(value.releaseDigest)
+  return { ...value }
+}
+export function parseOperationReceipt(value) {
+  value = JSON.parse(canonicalJson(value))
+  exact(value, ['operationId', 'state'], ['result', 'resultDigest'])
+  if (!/^[A-Za-z0-9_-]{16,128}$/.test(text(value.operationId)) || !['pending', 'admitted', 'succeeded', 'unknown', 'failed'].includes(value.state)) return reject()
+  if (value.state === 'succeeded') {
+    if (!Object.hasOwn(value, 'result')) return reject()
+    digest(value.resultDigest); canonicalJson(value.result)
+  } else if (Object.hasOwn(value, 'result') || Object.hasOwn(value, 'resultDigest')) return reject()
+  return JSON.parse(canonicalJson(value))
+}
+
+export function parseProviderOperationProof(value) {
+  const proof = JSON.parse(canonicalJson(value))
+  exact(proof, ['schema', 'installationId', 'generation', 'releaseDigest', 'operationId', 'actionId', 'payloadDigest', 'resultDigest', 'result'])
+  if (proof.schema !== 'mnstry.extension-provider-operation/v1' || !/^[A-Za-z0-9_-]{16,128}$/.test(text(proof.operationId))) return reject()
+  parseInstallationBinding({ installationId: proof.installationId, generation: proof.generation, releaseDigest: proof.releaseDigest })
+  text(proof.actionId); digest(proof.payloadDigest); digest(proof.resultDigest)
+  return proof
+}
+
+
+/** Portable registration input. The receiving host independently verifies the
+ * release and file hashes; this parser performs no I/O or migration execution. */
+export function parseReleaseBundle(value) {
+  const bundle=exact(JSON.parse(canonicalJson(value)),['manifest','schemaFiles','migrationDigests'])
+  bundle.manifest=parseManifest(bundle.manifest)
+  for(const field of ['schemaFiles','migrationDigests']) {
+    const map=bundle[field]
+    if(!map||typeof map!=='object'||Array.isArray(map)||Object.getPrototypeOf(map)!==Object.prototype)throw new ExtensionError('invalid-input')
+  }
+  if(Object.keys(bundle.schemaFiles).length>256)throw new ExtensionError('invalid-input')
+  for(const [name,bytes] of Object.entries(bundle.schemaFiles)) {
+    if(!/^schemas\/[A-Za-z0-9._-]+\.json$/.test(name)||typeof bytes!=='string'||new TextEncoder().encode(bytes).length>65536)throw new ExtensionError('invalid-input')
+    let schema
+    try{schema=JSON.parse(bytes)}catch{throw new ExtensionError('invalid-input')}
+    if(typeof schema!=='boolean'&&(!schema||typeof schema!=='object'||Array.isArray(schema)))throw new ExtensionError('invalid-input')
+    canonicalJson(schema)
+  }
+  for(const [name,digest] of Object.entries(bundle.migrationDigests)) {
+    if(!/^migrations\/[A-Za-z0-9._/-]+$/.test(name)||name.split('/').some(part=>!part||part==='.'||part==='..')||typeof digest!=='string'||!/^[a-f0-9]{64}$/.test(digest))throw new ExtensionError('invalid-input')
+  }
+  for(const action of bundle.manifest.actions)for(const field of ['inputSchemaRef','outputSchemaRef'])if(!Object.hasOwn(bundle.schemaFiles,action[field]))throw new ExtensionError('invalid-input')
+  return bundle
+}

package/src/extensions/convex.d.mts

@@ -0,0 +1,24 @@
+import type { GenericDataModel, GenericMutationCtx, GenericQueryCtx } from 'convex/server'
+import type { ExtensionManifest, Json, OperationReceipt, ProviderOperationProof } from './contracts.mjs'
+import type { VerifiedScope } from './server.mjs'
+export interface ConvexVerifierOptions {
+  issuer: string; audience: string; installationId: string; releaseDigest: string;
+  keys: ReadonlyMap<string, JsonWebKey>; now?: () => number;
+  consume?(claims: Readonly<Record<string, unknown>>, delegation: string): Promise<boolean>;
+}
+export interface ConvexActionDefinition<I = Json, O = Json, D extends GenericDataModel = GenericDataModel> {
+  input(value: unknown): I; output(value: unknown): O;
+  run(context: { context: GenericMutationCtx<D>; scope: VerifiedScope }, input: I): unknown | Promise<unknown>;
+}
+export interface ConvexExtension { readonly manifest: ExtensionManifest }
+export function convexDigest(value: unknown): Promise<string>
+export function assertConvexScope(scope: VerifiedScope): void
+export function defineConvexExtension<D extends GenericDataModel = GenericDataModel>(options: {
+  manifest: ExtensionManifest; verifier: ConvexVerifierOptions; actions: Record<string, ConvexActionDefinition<any, any, D>>;
+}): ConvexExtension
+export function createRootAdmissionConsumer(options: { origin: string; allowLocalTesting?: boolean; fetch?: typeof fetch }): NonNullable<ConvexVerifierOptions['consume']>
+export function createConvexHttpHandler(extension: ConvexExtension, invoke: (args: { delegation: string; payload: Json }) => Promise<OperationReceipt>): (request: Request) => Promise<Response>
+export function runConvexInvocation<D extends GenericDataModel>(extension: ConvexExtension, context: GenericMutationCtx<D>, args: { delegation: string; payload: Json }): Promise<OperationReceipt>
+export function onceConvexOperation<D extends GenericDataModel>(context: GenericMutationCtx<D>, scope: VerifiedScope, input: Json, run: (context: GenericMutationCtx<D>) => Promise<Json>): Promise<Json>
+export function lookupConvexOperation<D extends GenericDataModel>(context: GenericMutationCtx<D>, scope: VerifiedScope, operationId: string): Promise<ProviderOperationProof | null>
+export function convexHealth<D extends GenericDataModel>(context: GenericQueryCtx<D>, manifest: ExtensionManifest): Promise<{ schema: 'mnstry.extension-health/v1'; ready: true; profile: 'convex-native'; releaseDigest: string; schemaDigest: string }>

package/src/extensions/convex.mjs

@@ -0,0 +1,189 @@
+// Native Convex functions use Web Crypto and the existing delegation protocol.
+// This module imports no Node runtime, database driver or Convex admin client.
+import { canonicalJson, exact, ExtensionError, parseManifest, parseOperationReceipt, text } from './contracts.mjs'
+import { assertDelegationBinding, decodeBase64Url, decodeDelegation, delegationScope, unauthorized, validateDelegationClaims } from './delegation.mjs'
+import { createAdmissionConsumer, readInvocationBody } from './admission.mjs'
+
+// Convex bundles may replace NODE_ENV at build time. Authorize the optional
+// loopback test transport only when BOTH provider-owned deployment URLs are local.
+export function createRootAdmissionConsumer(options) {
+  const localRuntime = ['CONVEX_CLOUD_URL', 'CONVEX_SITE_URL'].every(name => {
+    try {
+      const url = new URL(process.env[name])
+      return url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname) &&
+        !url.username && !url.password && url.pathname === '/' && !url.search && !url.hash
+    } catch { return false }
+  })
+  return createAdmissionConsumer(options, options.allowLocalTesting === true && localRuntime)
+}
+
+const definitions = new WeakMap()
+const scopes = new WeakMap()
+const encoder = new TextEncoder()
+const freeze = value => {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value) }
+  return value
+}
+export async function convexDigest(value) {
+  const bytes = await crypto.subtle.digest('SHA-256', encoder.encode(canonicalJson(value)))
+  return [...new Uint8Array(bytes)].map(byte => byte.toString(16).padStart(2, '0')).join('')
+}
+export function assertConvexScope(scope) {
+  if (!scope || !scopes.get(scope)?.()) return unauthorized()
+}
+export function defineConvexExtension({ manifest, verifier, actions }) {
+  const pinned = parseManifest(manifest)
+  if (pinned.deployment.profile !== 'convex-native' || pinned.actions.some(action => !Object.hasOwn(actions, action.id)) ||
+      Object.keys(actions).some(id => !pinned.actions.some(action => action.id === id))) throw new ExtensionError('invalid-input')
+  const keys = new Map()
+  for (const [id, value] of verifier.keys) {
+    text(id)
+    const jwk = exact(JSON.parse(canonicalJson(value)), ['kty', 'crv', 'x', 'y'], ['alg', 'use', 'key_ops', 'ext', 'kid'])
+    if (jwk.kty !== 'EC' || jwk.crv !== 'P-256' || (jwk.alg !== undefined && jwk.alg !== 'ES256') ||
+        (jwk.use !== undefined && jwk.use !== 'sig') || (jwk.key_ops !== undefined && (jwk.key_ops.length !== 1 || jwk.key_ops[0] !== 'verify')) ||
+        decodeBase64Url(jwk.x).length !== 32 || decodeBase64Url(jwk.y).length !== 32) throw new ExtensionError('invalid-input')
+    keys.set(id, freeze(jwk))
+  }
+  const normalized = Object.fromEntries(Object.entries(actions).map(([id, action]) => {
+    if (['input', 'output', 'run'].some(key => typeof action[key] !== 'function')) throw new ExtensionError('invalid-input')
+    return [id, Object.freeze({ input: action.input, output: action.output, run: action.run })]
+  }))
+  const runtime = Object.freeze({ manifest: freeze(pinned), verifier: Object.freeze({ ...verifier, keys }), actions: Object.freeze(normalized) })
+  const handle = Object.freeze({ manifest: runtime.manifest })
+  definitions.set(handle, runtime)
+  return handle
+}
+function definition(handle) {
+  const extension = definitions.get(handle)
+  if (!extension) throw new ExtensionError('invalid-input')
+  return extension
+}
+async function invocation(extension, delegation, payload) {
+  let claims
+  try {
+    const decoded = decodeDelegation(delegation)
+    const jwk = extension.verifier.keys.get(decoded.header.kid)
+    if (!jwk) return unauthorized()
+    const key = await crypto.subtle.importKey('jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify'])
+    if (!await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, key, decoded.signature, decoded.signed)) return unauthorized()
+    claims = validateDelegationClaims(decoded.claims, extension.verifier)
+    assertDelegationBinding(claims, extension.manifest, extension.verifier)
+  } catch { return unauthorized() }
+  const { releaseDigest: ignored, ...manifestBody } = extension.manifest
+  if (await convexDigest(manifestBody) !== extension.manifest.releaseDigest) throw new ExtensionError('invalid-input')
+  const declared = extension.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 encoded = canonicalJson(payload)
+  if (encoder.encode(encoded).length > 65536 || await convexDigest(payload) !== claims.payloadDigest) throw new ExtensionError('invalid-input')
+  const input = action.input(JSON.parse(encoded))
+  if (await convexDigest(input) !== claims.payloadDigest) throw new ExtensionError('invalid-input')
+  return { claims, declared, action, input }
+}
+function boundedResult(value, lookup = false) {
+  const encoded = canonicalJson(value)
+  if (encoder.encode(encoded).length > (lookup ? 65536 : 60 * 1024)) throw new ExtensionError('invalid-input')
+  // Leave the same nesting headroom required by the host's result/proof wrappers.
+  canonicalJson(lookup ? { result: value } : { result: { result: value } })
+  return JSON.parse(encoded)
+}
+/** Call ONLY from a registered internalMutation. Never accept a serialized scope.
+ * Convex's transaction atomically commits all native reads/writes or rolls back.
+ * Date.now is Convex's transaction-start time; this does not revoke an in-flight commit. */
+export async function runConvexInvocation(handle, context, args) {
+  exact(args, ['delegation', 'payload'])
+  const extension = definition(handle)
+  const { claims, declared, action, input } = await invocation(extension, args.delegation, args.payload)
+  const scope = delegationScope(claims)
+  const deadline = Math.min(claims.exp * 1000, (extension.verifier.now?.() ?? Date.now()) + declared.timeoutMs)
+  scopes.set(scope, () => deadline > (extension.verifier.now?.() ?? Date.now()))
+  try {
+    assertConvexScope(scope)
+    const lookup = claims.actionId === extension.manifest.recovery?.lookupActionId
+    const original = canonicalJson(boundedResult(await action.run({ context, scope }, input), lookup))
+    const result = boundedResult(action.output(JSON.parse(original)), lookup)
+    // Output validators may refuse a value, but cannot silently change the
+    // durable result that onceConvexOperation will expose during recovery.
+    if (canonicalJson(result) !== original) throw new ExtensionError('invalid-input')
+    const resultDigest = await convexDigest(result)
+    assertConvexScope(scope)
+    return { operationId: claims.operationId, state: 'succeeded', result, resultDigest }
+  } finally { scopes.delete(scope) }
+}
+/** HTTP action: check original delegation, consume Root admission once, then call
+ * the private native mutation with the ORIGINAL token and canonical payload. */
+export function createConvexHttpHandler(handle, invoke) {
+  const extension = definition(handle)
+  if (typeof invoke !== 'function' || typeof extension.verifier.consume !== 'function') 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, declared, input } = await invocation(extension, delegation, await readInvocationBody(request))
+      if (!await extension.verifier.consume(claims, delegation)) throw new ExtensionError('forbidden', 403)
+      admitted = true
+      const deadline = Math.min(claims.exp * 1000, (extension.verifier.now?.() ?? Date.now()) + declared.timeoutMs)
+      if (deadline <= (extension.verifier.now?.() ?? Date.now())) throw new ExtensionError('operation-unknown', 409)
+      const receipt = parseOperationReceipt(await invoke({ delegation, payload: input }))
+      if (receipt.state !== 'succeeded' || receipt.operationId !== claims.operationId || await convexDigest(receipt.result) !== receipt.resultDigest ||
+          deadline <= (extension.verifier.now?.() ?? Date.now())) throw new ExtensionError('operation-unknown', 409)
+      boundedResult(receipt.result, claims.actionId === extension.manifest.recovery?.lookupActionId)
+      return Response.json(receipt, { 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' } })
+    }
+  }
+}
+function scopedQuery(context, table, index, scope, operationId) {
+  assertConvexScope(scope)
+  return context.db.query(table).withIndex(index, query => {
+    const scoped = query.eq('installationId', scope.installationId).eq('tenantRef', scope.tenantRef).eq('subjectRef', scope.subjectRef)
+    return operationId === undefined ? scoped : scoped.eq('operationId', operationId)
+  })
+}
+/** Native indexed read/OCC conflict plus result insert, within ONE internal mutation. */
+export async function onceConvexOperation(context, scope, input, run) {
+  assertConvexScope(scope)
+  if (await convexDigest(input) !== scope.payloadDigest) throw new ExtensionError('invalid-input')
+  const row = await scopedQuery(context, 'extensionOperations', 'by_scope_operation', scope, scope.operationId).unique()
+  assertConvexScope(scope)
+  if (row) {
+    if (row.actionId !== scope.actionId || row.generation !== scope.generation || row.releaseDigest !== scope.releaseDigest || row.payloadDigest !== scope.payloadDigest) throw new ExtensionError('idempotency-conflict', 409)
+    if (await convexDigest(row.result) !== row.resultDigest) throw new ExtensionError('unavailable', 503)
+    return boundedResult(row.result)
+  }
+  const result = boundedResult(await run(context))
+  const resultDigest = await convexDigest(result)
+  assertConvexScope(scope)
+  const { rootWrites: omitted, ...identity } = scope
+  await context.db.insert('extensionOperations', { ...identity, result, resultDigest })
+  assertConvexScope(scope)
+  return result
+}
+export async function lookupConvexOperation(context, scope, operationId) {
+  assertConvexScope(scope)
+  if (!/^[A-Za-z0-9_-]{16,128}$/.test(text(operationId))) throw new ExtensionError('invalid-input')
+  const row = await scopedQuery(context, 'extensionOperations', 'by_scope_operation', scope, operationId).unique()
+  assertConvexScope(scope)
+  if (!row) return null
+  if (await convexDigest(row.result) !== row.resultDigest) throw new ExtensionError('unavailable', 503)
+  return { schema: 'mnstry.extension-provider-operation/v1', installationId: scope.installationId,
+    operationId: row.operationId, actionId: row.actionId, generation: row.generation, releaseDigest: row.releaseDigest,
+    payloadDigest: row.payloadDigest, resultDigest: row.resultDigest, result: row.result }
+}
+
+/** Read-only native index readiness; the existing host health envelope carries
+ * only immutable release/schema identities, never member rows or row counts. */
+export async function convexHealth(context, value) {
+  const manifest = parseManifest(value)
+  const { releaseDigest: ignored, ...body } = manifest
+  if (manifest.deployment.profile !== 'convex-native' || await convexDigest(body) !== manifest.releaseDigest) throw new ExtensionError('unavailable', 503)
+  await context.db.query('extensionCounters').withIndex('by_scope').take(0)
+  await context.db.query('extensionOperations').withIndex('by_scope_operation').take(0)
+  return { schema: 'mnstry.extension-health/v1', ready: true, profile: 'convex-native',
+    releaseDigest: manifest.releaseDigest, schemaDigest: manifest.deployment.schemaDigest }
+}

package/src/extensions/delegation.mjs

@@ -0,0 +1,54 @@
+// One delegation contract shared by Node and provider-native runtimes.
+import { exact, ExtensionError, text } from './contracts.mjs'
+
+export const unauthorized = () => { throw new ExtensionError('unauthorized', 401) }
+const claimNames = ['iss', 'aud', 'iat', 'nbf', 'exp', 'jti', 'purpose', 'installationId', 'tenantRef', 'subjectRef', 'generation', 'releaseDigest', 'operationId', 'actionId', 'payloadDigest', 'rootWrites']
+const opaque = value => /^[A-Za-z0-9_-]{16,128}$/.test(text(value))
+export function decodeBase64Url(part) {
+  if (typeof part !== 'string' || !/^[A-Za-z0-9_-]+$/.test(part)) return unauthorized()
+  const binary = atob(part.replace(/-/g, '+').replace(/_/g, '/'))
+  if (btoa(binary).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_') !== part) return unauthorized()
+  return Uint8Array.from(binary, char => char.charCodeAt(0))
+}
+function decodeJson(part) {
+  const bytes = decodeBase64Url(part)
+  const value = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  const encoded = new TextEncoder().encode(value)
+  if (encoded.length !== bytes.length || encoded.some((byte, index) => byte !== bytes[index])) return unauthorized()
+  return JSON.parse(value)
+}
+export function decodeDelegation(delegation) {
+  text(delegation, 16384)
+  const parts = delegation.split('.')
+  if (parts.length !== 3) return unauthorized()
+  const header = exact(decodeJson(parts[0]), ['alg', 'typ', 'kid'])
+  if (header.alg !== 'ES256' || header.typ !== 'JWT') return unauthorized()
+  text(header.kid)
+  const signature = decodeBase64Url(parts[2])
+  if (signature.length !== 64) return unauthorized()
+  return { header, claims: decodeJson(parts[1]), signature, signed: new TextEncoder().encode(`${parts[0]}.${parts[1]}`) }
+}
+export function validateDelegationClaims(value, options) {
+  const claims = exact(value, claimNames)
+  const now = Math.floor((options.now?.() ?? Date.now()) / 1000)
+  if (claims.iss !== options.issuer || claims.aud !== options.audience || claims.purpose !== 'extension.invoke/v1' ||
+      ![claims.iat, claims.nbf, claims.exp].every(Number.isSafeInteger) || claims.iat > now || claims.nbf !== claims.iat ||
+      claims.exp <= now || claims.exp <= claims.iat || claims.exp - claims.iat > 60) return unauthorized()
+  for (const field of ['jti', 'installationId', 'operationId', 'tenantRef', 'subjectRef']) if (!opaque(claims[field])) return unauthorized()
+  text(claims.actionId)
+  if (typeof claims.generation !== 'string' || typeof claims.releaseDigest !== 'string' || typeof claims.payloadDigest !== 'string' || !/^[1-9][0-9]{0,18}$/.test(claims.generation) || BigInt(claims.generation) > 9223372036854775807n ||
+      !/^[a-f0-9]{64}$/.test(claims.releaseDigest) || !/^[a-f0-9]{64}$/.test(claims.payloadDigest) ||
+      !Array.isArray(claims.rootWrites) || claims.rootWrites.length > 64 || new Set(claims.rootWrites).size !== claims.rootWrites.length) return unauthorized()
+  claims.rootWrites.forEach(value => text(value, 256))
+  return Object.freeze({ ...claims, rootWrites: Object.freeze([...claims.rootWrites]) })
+}
+export function assertDelegationBinding(claims, manifest, verifier) {
+  if (claims.installationId !== verifier.installationId || claims.releaseDigest !== manifest.releaseDigest ||
+      claims.releaseDigest !== verifier.releaseDigest || claims.rootWrites.length !== manifest.permissions.rootWrites.length ||
+      claims.rootWrites.some(value => !manifest.permissions.rootWrites.includes(value))) return unauthorized()
+}
+export function delegationScope(claims) {
+  return 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 })
+}

package/src/extensions/drizzle.d.mts

@@ -0,0 +1,11 @@
+import type { Sql } from 'postgres'
+import type { Json, ProviderOperationProof } from './contracts.mjs'
+import type { VerifiedScope } from './server.mjs'
+export interface DrizzleTransaction { execute(query: any): PromiseLike<any> }
+/** Native drizzle-orm/postgres-js database; other drivers are unsupported. */
+export interface DrizzleDatabase<Transaction extends DrizzleTransaction> { readonly $client: Sql; transaction<T>(run:(transaction:Transaction)=>Promise<T>):Promise<T> }
+export type DrizzleSqlTag = (chunks:TemplateStringsArray,...values:any[])=>unknown
+export function withDrizzleScope<Transaction extends DrizzleTransaction,T>(database: DrizzleDatabase<Transaction>, scope: VerifiedScope, sql: DrizzleSqlTag, run: (transaction: Transaction) => Promise<T>): Promise<T>
+export function onceDrizzleOperation<Transaction extends DrizzleTransaction>(database: DrizzleDatabase<Transaction>, scope: VerifiedScope, input: Json, sql: DrizzleSqlTag, run: (transaction: Transaction) => Promise<Json>): Promise<Json>
+export function lookupDrizzleOperation<Transaction extends DrizzleTransaction>(database:DrizzleDatabase<Transaction>,scope:VerifiedScope,sql:DrizzleSqlTag,operationId:string):Promise<ProviderOperationProof|null>
+export function drizzleHealth(driver: Sql, profile: 'drizzle-db-first'|'drizzle-code-first'): Promise<{ ready: true; profile: 'drizzle-db-first'|'drizzle-code-first'; postgresMajor: 17 }>

package/src/extensions/drizzle.mjs

@@ -0,0 +1,33 @@
+import { withPostgresScope, oncePostgresOperation, lookupPostgresOperation, postgresHealth } from './postgres.mjs'
+import { ExtensionError } from './contracts.mjs'
+
+// The native ORM owns the transaction. The application supplies its SQL tag;
+// Atelier never imports the optional ORM or reconstructs it around a driver tx.
+function bridge(database, sqlTag) {
+  if(typeof database?.transaction!=='function'||typeof sqlTag!=='function')throw new ExtensionError('invalid-input')
+  const transactions=new WeakMap()
+  return { transactions, database:{begin:callback=>database.transaction(tx=>{
+    const query=(chunks,...values)=>tx.execute(sqlTag(chunks,...values))
+    query.json=value=>JSON.stringify(value)
+    transactions.set(query,tx)
+    return callback(query)
+  })} }
+}
+export async function withDrizzleScope(database, scope, sqlTag, run) {
+  if(typeof run!=='function')throw new ExtensionError('invalid-input')
+  const native=bridge(database,sqlTag)
+  return withPostgresScope(native.database,scope,query=>run(native.transactions.get(query)))
+}
+export async function onceDrizzleOperation(database, scope, input, sqlTag, run) {
+  if(typeof run!=='function')throw new ExtensionError('invalid-input')
+  const native=bridge(database,sqlTag)
+  return oncePostgresOperation(native.database,scope,input,query=>run(native.transactions.get(query)))
+}
+export async function lookupDrizzleOperation(database,scope,sqlTag,operationId) {
+  return lookupPostgresOperation(bridge(database,sqlTag).database,scope,operationId)
+}
+export async function drizzleHealth(driver, profile) {
+  if (!['drizzle-db-first', 'drizzle-code-first'].includes(profile)) throw new ExtensionError('invalid-input')
+  const health = await postgresHealth(driver)
+  return { ...health, profile }
+}

package/src/extensions/postgres.d.mts

@@ -0,0 +1,7 @@
+import type { Sql, TransactionSql } from 'postgres'
+import type { Json, ProviderOperationProof } from './contracts.mjs'
+import type { VerifiedScope } from './server.mjs'
+export function withPostgresScope<T>(database: Sql, scope: VerifiedScope, run: (sql: TransactionSql) => Promise<T>): Promise<T>
+export function oncePostgresOperation(database: Sql, scope: VerifiedScope, input: Json, run: (sql: TransactionSql) => Promise<Json>): Promise<Json>
+export function lookupPostgresOperation(database: Sql, scope: VerifiedScope, operationId: string): Promise<ProviderOperationProof|null>
+export function postgresHealth(database: Sql): Promise<{ ready: true; profile: 'postgres-sql'; postgresMajor: 17 }>