@runeditrun/rer 0.0.0-stage → 0.1.0

package/modules/deploy-kit/health-request.mjs

@@ -0,0 +1,86 @@
+import { assert } from './validation.mjs';
+
+async function bodyPrefix(response) {
+  if (!response.body) return '';
+  const reader = response.body.getReader(); let bytes = Buffer.alloc(0);
+  try {
+    while (bytes.length < 256) {
+      const {done,value} = await reader.read();
+      if (done) break;
+      bytes = Buffer.concat([bytes,value.subarray(0,256-bytes.length)]);
+    }
+  } catch { /* HTTP status remains authoritative if its diagnostic body breaks. */ }
+  finally { await reader.cancel().catch(() => {}); }
+  return bytes.toString('utf8');
+}
+
+/** One credential-free, bounded request. Retain only bounded response evidence. */
+export async function healthRequest({origin, receipt, versionId, request, timeoutMs, offsetMs}) {
+  const attempt = {offsetMs,status:null,cfRay:null,contentType:null,body:'',errorClass:null};
+  let response;
+  try {
+    response = await request(`${origin}/health`, {redirect:'manual',signal:AbortSignal.timeout(timeoutMs),headers:{'Cache-Control':'no-cache','Accept':'application/json'}});
+  } catch {
+    attempt.errorClass = 'health-transport-failed';
+    return {attempt,transient:true};
+  }
+  attempt.status = response.status;
+  attempt.cfRay = response.headers.get('cf-ray')?.slice(0,256) ?? null;
+  attempt.contentType = response.headers.get('content-type')?.slice(0,256) ?? null;
+  if (response.status !== 200 || response.redirected) {
+    attempt.body = await bodyPrefix(response);
+    attempt.errorClass = 'health-http-failed';
+    return {attempt,transient:!response.redirected && (response.status === 404 || response.status >= 500 && response.status <= 599)};
+  }
+  let bytes = Buffer.alloc(0);
+  try {
+    assert(response.body,'empty-response');
+    const reader = response.body.getReader();
+    try {
+      while (true) {
+        const {done,value} = await reader.read();
+        if (done) break;
+        bytes = Buffer.concat([bytes, value]);
+        attempt.body = bytes.subarray(0,256).toString('utf8');
+        assert(bytes.length <= 65536,'response-too-large');
+      }
+    } finally { await reader.cancel().catch(() => {}); }
+  } catch (error) {
+    attempt.errorClass = ['response-too-large','empty-response'].includes(error.message) ? error.message : 'health-transport-failed';
+    // A redirect or permanent status can never become retryable via body IO.
+    return {attempt,transient:attempt.errorClass === 'health-transport-failed' && (response.status === 200 || response.status === 404 || response.status >= 500 && response.status <= 599)};
+  }
+  let body;
+  try { body = JSON.parse(bytes.toString('utf8')); }
+  catch { attempt.errorClass = 'malformed-response'; return {attempt,transient:false}; }
+  if (body?.ok !== true || body.deployment?.sourceSha !== receipt.source.sha || body.deployment?.fingerprint !== receipt.fingerprint || body.deployment?.versionId !== versionId) {
+    attempt.errorClass = 'health-identity-mismatch';
+  }
+  return {attempt,transient:false};
+}
+
+/** Retries are spaced 1 s, doubling to a 10 s cap, never closer than the 2 s poll
+ * interval of the standalone readiness window: 2, 2, 4, 8, 10, 10 ... seconds. */
+const MIN_DELAY_MS = 2000, MAX_DELAY_MS = 10000;
+
+/** The total bound includes requests, body reads and backoff; no request starts at the deadline.
+ * Only a transient outcome is retried. Every attempt is recorded, in order, whatever the end. */
+export async function waitHealth({origin,receipt,versionId,request,timeoutMs=30000,totalMs=90000,clock=()=>performance.now(),sleep=ms=>new Promise(resolve=>setTimeout(resolve,ms)),onAttempt=()=>{},single=false}) {
+  assert(Number.isFinite(totalMs) && totalMs > 0 && totalMs <= 90000 && Number.isFinite(timeoutMs) && timeoutMs > 0,'invalid-health-bound');
+  const start = clock(); const attempts = []; let delay = 1000;
+  while (true) {
+    const remaining = totalMs - (clock()-start);
+    if (remaining <= 0) break;
+    const result = await healthRequest({origin,receipt,versionId,request,timeoutMs:Math.max(1,Math.ceil(Math.min(timeoutMs,remaining))),offsetMs:Math.round(clock()-start)});
+    attempts.push(result.attempt); await onAttempt(result.attempt,attempts);
+    if (!result.attempt.errorClass) return {ok:true,versionId,attempts};
+    if (single || !result.transient) break;
+    const rest = totalMs - (clock()-start);
+    if (rest <= 0) break;
+    await sleep(Math.min(Math.max(delay,MIN_DELAY_MS),rest)); delay = Math.min(delay*2,MAX_DELAY_MS);
+  }
+  const last = attempts.at(-1);
+  const error = new Error(`${last?.errorClass ?? 'health-timeout'}-last-status-${last?.status ?? 'transport'}`);
+  error.attempts = attempts; error.status = last?.status ?? null;
+  throw error;
+}

package/modules/deploy-kit/health.mjs

@@ -0,0 +1,99 @@
+import { verifyServiceGrants } from './service-grants.mjs';
+import { assert, stable } from './validation.mjs';
+import { boundedJSON } from './provider.mjs';
+import { activeWorker, workerOrigin, durableNamespaces, verifyScheduledHandler } from './worker.mjs';
+import { reconcileResources, reconcileTriggers } from './resources.mjs';
+import { migrate } from './migrations.mjs';
+import { bindingsFor, verifyBindings } from './render.mjs';
+import { waitHealth } from './health-request.mjs';
+
+function healthError(message, code, lastResult) {
+  const error = new Error(message); error.code = code; error.lastResult = lastResult; return error;
+}
+
+/** Cloudflare may publish the route/bindings shortly after an upload succeeds.
+ * Only 404, 503 and network failures are retried, inside one bounded window;
+ * every other status, including redirects, is terminal and never healthy. */
+export async function waitForDeploymentHealth(url, {
+  timeoutMs = 30_000,
+  intervalMs = 2_000,
+  attemptTimeoutMs = 5_000,
+  headers,
+  fetchImpl = globalThis.fetch,
+  now = Date.now,
+  sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+} = {}) {
+  const deadline = now() + timeoutMs;
+  let lastResult = 'no response';
+  while (now() < deadline) {
+    let response;
+    try {
+      response = await fetchImpl(url, { redirect: 'manual', signal: AbortSignal.timeout(Math.max(1, Math.min(attemptTimeoutMs, deadline - now()))), ...(headers ? { headers } : {}) });
+    } catch {
+      lastResult = 'network error';
+    }
+    if (response) {
+      if (response.ok) return response;
+      lastResult = `HTTP ${response.status}`;
+      await response.body?.cancel().catch(() => {});
+      if (response.status !== 404 && response.status !== 503) {
+        throw healthError(`Deployment health check failed at ${url}: ${lastResult}.`, 'health-http-failed', lastResult);
+      }
+    }
+    const remaining = deadline - now();
+    if (remaining > 0) await sleep(Math.min(intervalMs, remaining));
+  }
+  throw healthError(`Deployment did not become healthy at ${url} within ${timeoutMs}ms; last result: ${lastResult}.`, lastResult === 'network error' ? 'health-transport-failed' : 'health-http-failed', lastResult);
+}
+
+/** One unauthenticated GET of a built file; anything but 200 means the browser gets no assets. */
+async function servedAsset(origin, path, request, timeoutMs) {
+  let response;
+  try { response = await request(`${origin}/${path.split('/').map(encodeURIComponent).join('/')}`,{redirect:'manual',signal:AbortSignal.timeout(timeoutMs),headers:{'Cache-Control':'no-cache'}}); }
+  catch { throw new Error('asset-transport-failed'); }
+  await response.body?.cancel().catch(() => {});
+  assert(response.status === 200 && !response.redirected,'asset-http-failed');
+  return {path,status:response.status};
+}
+
+/** Authenticated provider readback, then the unauthenticated account-derived /health.
+ * Without `readiness`, /health gets the single bounded window of waitForDeploymentHealth.
+ * With `readiness` (deploy after an upload) it gets the recorded 90-second wait of health-request.mjs.
+ * `asset`, a built file's path, is then requested once and must answer 200. */
+export async function verifyHealth({api,plan,receipt,fetch:request=globalThis.fetch,timeoutMs=30000,intervalMs=2000,now,sleep,readiness,asset}) {
+  assert(receipt?.version === 1 && receipt.accountId === api.accountId && receipt.worker === plan.worker,'receipt-target-mismatch');
+  await verifyServiceGrants(api, plan);
+  const current = await activeWorker(api,plan.worker);
+  assert(current && current.versionId === receipt.provider.versionId && current.deploymentId === receipt.provider.deploymentId && current.etag === receipt.provider.etag,'active-deployment-mismatch');
+  verifyScheduledHandler(current,plan);
+  const origin = await workerOrigin(api,plan.worker,{workersDev:plan.workersDev !== false});
+  assert(origin === receipt.origin,'health-origin-mismatch');
+  const resources = await reconcileResources(api,plan,{create:false});
+  assert(stable(resources) === stable(receipt.resources),'resource-identity-drift');
+  verifyBindings(current.settings.bindings,bindingsFor(receipt.config,resources,plan));
+  await reconcileTriggers(api,plan,resources,{mutate:false});
+  const namespaces = await durableNamespaces(api,plan,{requireAll:true});
+  assert(stable(namespaces) === stable(receipt.durableObjects),'durable-object-identity-drift');
+  for (const item of plan.d1) await migrate(api,resources.d1.find(x => x.binding === item.binding).id,item.migrations,{apply:false});
+  const secrets = await api.request(`/workers/scripts/${plan.worker}/secrets`);
+  assert(Array.isArray(secrets) && plan.secrets.every(x => secrets.some(y => y.name === x.binding && y.type === 'secret_text')),'missing-deployed-secret');
+  let health;
+  // A Worker without a public route (reached only through service bindings) has no /health to request.
+  if (plan.workersDev === false) health = {ok:true,versionId:current.versionId,route:'none'};
+  else if (readiness) health = await waitHealth({origin,receipt,versionId:current.versionId,request,timeoutMs,...readiness});
+  else {
+    let response;
+    try {
+      response = await waitForDeploymentHealth(`${origin}/health`,{timeoutMs,intervalMs,attemptTimeoutMs:timeoutMs,headers:{'Cache-Control':'no-cache','Accept':'application/json'},fetchImpl:request,...(now ? {now} : {}),...(sleep ? {sleep} : {})});
+    } catch (error) { throw new Error(error.code ?? 'health-transport-failed'); }
+    assert(response.ok && response.status === 200 && !response.redirected,'health-http-failed');
+    const body = await boundedJSON(response,65536);
+    assert(body?.ok === true && body.deployment?.sourceSha === receipt.source.sha && body.deployment?.fingerprint === receipt.fingerprint && body.deployment?.versionId === current.versionId,'health-identity-mismatch');
+    health = {ok:true,versionId:current.versionId};
+  }
+  if (asset && origin) health.asset = await servedAsset(origin,asset,request,timeoutMs);
+  const after = await activeWorker(api,plan.worker);
+  assert(after.versionId === current.versionId && after.deploymentId === current.deploymentId && after.etag === current.etag,'deployment-changed-during-health');
+  await verifyServiceGrants(api, plan);
+  return health;
+}

package/modules/deploy-kit/index.mjs

@@ -0,0 +1,12 @@
+export { cloudflare } from './provider.mjs';
+export { deploy } from './deploy.mjs';
+export { verifyHealth, waitForDeploymentHealth } from './health.mjs';
+export { ownerWorkerName, ownerResourceName, ownerTarget, ownerPlan, localOnlyBinding, LOCAL_ONLY_KEYS, ownerDeploy, ownerHealth, readOwnerState, withScopeHints } from './owner.mjs';
+export { verifyTeardown, deleteWorker } from './teardown.mjs';
+export { writeHealthReceipt } from './receipt.mjs';
+export { workerConsumerScript } from './queue-consumer.mjs';
+export { readArtifact } from './artifact.mjs';
+export { renderConfig } from './render.mjs';
+export { defaultStagePlan, stage } from './default-stage.mjs';
+export { check, mailPlan } from './check.mjs';
+export { createTemplates, lockTemplates } from './templates.mjs';

package/modules/deploy-kit/local-only.mjs

@@ -0,0 +1,10 @@
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const LOCAL_MODELS_FILE = '.rer/local/models.json';
+/** Refuse presence, including symlinks: never read this key to build a plan. */
+export async function refuseLocalModels(root) {
+  try { await lstat(join(root, LOCAL_MODELS_FILE)); }
+  catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  throw new Error('local-only-models-file');
+}

package/modules/deploy-kit/migrations.mjs

@@ -0,0 +1,48 @@
+import { assert, hash } from './validation.mjs';
+import { assertMigrationSqlSafe } from './sql-safety.mjs';
+import { sqlTokens } from './sql-tokens.mjs';
+const ledger = '_rer_deploy_migrations';
+const literal = value => `'${value.replaceAll("'","''")}'`;
+export function validateMigrations(migrations) {
+  let previous = '';
+  for (const migration of migrations) {
+    assert(/^[0-9]+_[a-zA-Z0-9_-]+\.sql$/.test(migration.name) && migration.name > previous, 'migration-order-or-name'); previous = migration.name;
+    assert(typeof migration.sql === 'string' && migration.sql.trim() && hash(migration.sql) === migration.sha256 && migration.sql.length <= 512000, 'invalid-migration-bytes');
+    assertMigrationSqlSafe(migration.sql);
+    assert(sqlTokens(migration.sql).length > 0, 'invalid-migration-bytes');
+  }
+}
+export async function query(api, id, sql) {
+  const rows = await api.request(`/d1/database/${id}/query`,{method:'POST',body:{sql}});
+  assert(Array.isArray(rows) && rows.length > 0 && rows.every(x => x.success === true && Array.isArray(x.results)), 'd1-query-failed');
+  return rows;
+}
+export async function migrate(api, id, migrations, { apply = true } = {}) {
+  validateMigrations(migrations);
+  const tables = (await query(api,id,"SELECT name FROM sqlite_master WHERE type='table' AND name IN ('_rer_deploy_migrations','d1_migrations')"))[0].results.map(x => x.name);
+  let applied = [];
+  if (tables.includes(ledger)) applied = (await query(api,id,`SELECT name, sha256, state FROM ${ledger} ORDER BY name`))[0].results;
+  // Wrangler history has no hashes. Never assume old SQL bytes from its names alone.
+  if (tables.includes('d1_migrations')) {
+    const prior = (await query(api,id,'SELECT name FROM d1_migrations ORDER BY id'))[0].results;
+    assert(prior.every(x => applied.some(y => x.name === y.name && y.state === 'applied')), 'legacy-migration-history-needs-reviewed-hash-adoption');
+  }
+  assert(applied.every((row,index) => row.name === migrations[index]?.name && row.sha256 === migrations[index]?.sha256 && row.state === 'applied'), 'changed-or-uncertain-migration-history');
+  const pending = migrations.slice(applied.length);
+  assert(apply || pending.length === 0,'pending-migrations');
+  if (pending.length && !tables.includes(ledger)) await query(api,id,`CREATE TABLE ${ledger} (name TEXT PRIMARY KEY, sha256 TEXT NOT NULL, state TEXT NOT NULL CHECK(state IN ('applying','applied')))`);
+  for (const migration of pending) {
+    // Claim before execution. A lost response/partial provider failure is never automatically replayed.
+    await query(api,id,`INSERT INTO ${ledger}(name,sha256,state) VALUES (${literal(migration.name)},${literal(migration.sha256)},'applying')`);
+    const last = sqlTokens(migration.sql).at(-1);
+    // A second terminator after trailing comments creates an empty D1 statement.
+    // Keep the newline even when terminated: a final line comment must end.
+    const separator = last?.kind === 'symbol' && last.value === ';' ? '' : '; ';
+    await query(api,id,`${migration.sql}\n${separator}UPDATE ${ledger} SET state='applied' WHERE name=${literal(migration.name)} AND sha256=${literal(migration.sha256)};`);
+  }
+  if (pending.length) {
+    const final = (await query(api,id,`SELECT name, sha256, state FROM ${ledger} ORDER BY name`))[0].results;
+    assert(final.length === migrations.length && final.every((x,i) => x.state === 'applied' && x.name === migrations[i].name && x.sha256 === migrations[i].sha256), 'migration-readback-mismatch');
+  }
+  return { applied:pending.map(x => x.name), history:migrations.map(({name,sha256}) => ({name,sha256})) };
+}

package/modules/deploy-kit/owner-cli.mjs

@@ -0,0 +1,63 @@
+import { execFileSync } from 'node:child_process';
+import { resolve, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { assert, hexId } from './validation.mjs';
+import { regularBytes } from './artifact.mjs';
+import { packageBuild } from './prepare.mjs';
+import { cloudflare } from './provider.mjs';
+import { ownerTarget, ownerPlan, ownerDeploy, ownerHealth } from './owner.mjs';
+import { refuseLocalModels } from './local-only.mjs';
+
+export const cronNotice = 'This Worker has a Cron Trigger. Cloudflare may take up to about two hours to start its first scheduled run on some accounts.';
+const usage = 'usage: owner-cli.mjs deploy|health --declaration <file> --environment <name> [--product <dir>] [--state <file>]';
+
+/** The owner's committed source and existing local build. Run the seed's build first. */
+async function ownerArtifact(root, product) {
+  const git = (...args) => { try { return execFileSync('git',args,{cwd:root,encoding:'utf8',stdio:['ignore','pipe','pipe']}).trim(); } catch { throw new Error('owner-source-not-a-git-checkout'); } };
+  const source = {sha:git('rev-parse','HEAD'),tree:git('rev-parse','HEAD^{tree}')};
+  assert(!git('status','--porcelain','--untracked-files=no'),'owner-source-not-committed');
+  return packageBuild({root,source,runIdentity:{id:'0',attempt:'1'},productDirectory:product});
+}
+
+/** Inputs: CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, plus the secrets the declaration names on first deploy. */
+export async function main(argv = process.argv.slice(2), env = process.env, {fetch = globalThis.fetch, cwd = process.cwd(), healthOptions, localOnlyKeys = [], notice = line => console.error(line)} = {}) {
+  let parsed;
+  try { parsed = parseArgs({args:argv,allowPositionals:true,strict:true,options:{declaration:{type:'string'},environment:{type:'string'},product:{type:'string',default:''},state:{type:'string'}}}); }
+  catch { throw new Error('usage'); }
+  const {positionals:[command,...rest],values} = parsed;
+  if (!['deploy','health'].includes(command) || rest.length || !values.declaration || !values.environment) throw new Error('usage');
+  await refuseLocalModels(resolve(cwd));
+  const missing = ['CLOUDFLARE_ACCOUNT_ID','CLOUDFLARE_API_TOKEN'].filter(key => typeof env[key] !== 'string' || !env[key].trim());
+  if (missing.length) { const error = new Error('missing-input'); error.inputs = missing; throw error; }
+  assert(hexId(env.CLOUDFLARE_ACCOUNT_ID) && !/[\r\n]/.test(env.CLOUDFLARE_API_TOKEN),'invalid-cloudflare-input');
+  const root = resolve(cwd);
+  let declaration;
+  try { declaration = JSON.parse(await regularBytes(resolve(root,values.declaration),256 * 1024)); }
+  catch (error) { throw new Error(error.code === 'ENOENT' ? 'missing-owner-declaration' : 'invalid-owner-declaration'); }
+  assert(typeof declaration?.project === 'string','missing-owner-project');
+  const api = cloudflare({accountId:env.CLOUDFLARE_ACCOUNT_ID,token:env.CLOUDFLARE_API_TOKEN,fetch});
+  const target = await ownerTarget(api,{project:declaration.project,environment:values.environment});
+  const statePath = values.state ? resolve(root,values.state) : join(root,'.rer','deploy',`${target.environment}.json`);
+  const artifact = await ownerArtifact(root,values.product);
+  const plan = ownerPlan(target,declaration,artifact,{localOnlyKeys});
+  if (command === 'health') {
+    await ownerHealth({api,target,plan,statePath,fetch,healthOptions:{...healthOptions,readiness:{single:true,totalMs:30000}}});
+    return {ok:true,worker:target.worker,origin:target.origin};
+  }
+  // Dispatch is the provider's: on some accounts a new Cron starts only at the account scheduler's next refresh.
+  if (plan.crons.length) notice(cronNotice);
+  const {receipt,created} = await ownerDeploy({api,target,plan,artifact,statePath,env,fetch,healthOptions});
+  return {ok:true,changed:receipt.changed,worker:target.worker,origin:receipt.origin,versionId:receipt.provider.versionId,created,state:statePath};
+}
+
+/** Prints refusal codes and resource names only; never inputs, tokens or provider bodies. */
+export function report(error) {
+  if (error.message === 'missing-input') return {ok:false,code:'missing-input',inputs:error.inputs};
+  if (error.message === 'usage') return {ok:false,code:'usage',usage};
+  return {ok:false,code:/^[a-zA-Z0-9_-]{1,120}$/.test(error.message) ? error.message : 'owner-deploy-failed',...(error.resource ? {resource:error.resource} : {})};
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try { console.log(JSON.stringify(await main())); }
+  catch (error) { console.error(JSON.stringify(report(error))); process.exitCode = error.message === 'local-only-binding' ? 4 : 1; }
+}

package/modules/deploy-kit/owner.mjs

@@ -0,0 +1,297 @@
+import { ingressBindings } from './container-config.mjs';
+import { mkdir, open, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { assert, hash, identifier, resourceName, validatePlan } from './validation.mjs';
+import { regularBytes } from './artifact.mjs';
+import { resourceKinds, findResource, checkCronOwnership } from './resources.mjs';
+import { secretBindings, activeWorker, deployedFingerprint } from './worker.mjs';
+import { validateMigrations } from './migrations.mjs';
+import { deploy } from './deploy.mjs';
+import { verifyHealth } from './health.mjs';
+
+/* Owner-account mode: the owner's own Cloudflare account, token and account id.
+ * Names are derived from the project id and the owner's environment. A local
+ * state file records what this kit created; a same-named resource it did not
+ * create is refused, never adopted. */
+
+const segment = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const STATE_KIND = 'rer-deploy-owner-state';
+const KINDS = ['d1','r2','kv','queues'];
+const DECLARATION_KEYS = ['version','project','compatibilityDate','compatibilityFlags','d1','r2','kv','queues','durableObjects','secrets','crons','vars','originVar','services','workersDev','platforms','container'];
+const ENTRY_KEYS = {d1:['binding'],r2:['binding','locationHint'],kv:['binding'],queues:['binding','consumer','deadLetterQueue'],durableObjects:['binding','className','storage'],secrets:['binding','environment'],services:['binding','project','entrypoint','allowedHosts','grant']};
+
+function refuse(code, kind, name) { const error = new Error(code); error.resource = `${kind}:${name}`; return error; }
+
+export function ownerWorkerName(project, environment) {
+  assert(typeof project === 'string' && /^(?:[a-z0-9][a-z0-9-]*\/)?[a-z0-9-]+$/.test(project) && segment.test(project.split('/').at(-1)), 'invalid-owner-project');
+  assert(typeof environment === 'string' && environment.length <= 32 && segment.test(environment), 'invalid-owner-environment');
+  const worker = `${project.split('/').at(-1)}-${environment}`;
+  assert(resourceName(worker), 'owner-name-too-long');
+  return worker;
+}
+/** `JOBS_DEAD` on Worker `penny-production` is named `penny-production-jobs-dead`. */
+export function ownerResourceName(worker, binding) {
+  assert(identifier(binding), 'duplicate-or-invalid-binding');
+  const slug = binding.toLowerCase().replaceAll('_','-');
+  assert(segment.test(slug), 'invalid-owner-binding');
+  assert(resourceName(`${worker}-${slug}`), 'owner-name-too-long');
+  return `${worker}-${slug}`;
+}
+/* A 401 or 403 on a known path names the token permission that failed, never the request. */
+const SCOPES = [[/^\/d1\//,'d1'],[/^\/r2\//,'r2'],[/^\/storage\/kv\//,'kv'],[/^\/queues(?:[/?]|$)/,'queues'],[/^\/workers\//,'workers']];
+export function withScopeHints(api) {
+  if (api.scopeHints) return api;
+  const hint = (path, error) => {
+    const scope = (error.status === 401 || error.status === 403) && SCOPES.find(([pattern]) => pattern.test(path));
+    if (scope) error.message = `token-scope-missing-${scope[1]}`;
+    throw error;
+  };
+  const guard = method => async (path, ...rest) => { try { return await api[method](path, ...rest); } catch (error) { return hint(path, error); } };
+  return {...api, scopeHints:true, request:guard('request'), envelope:guard('envelope'), list:guard('list')};
+}
+/** Reads the account's workers.dev subdomain; no other provider request. */
+export async function ownerTarget(provider, {project, environment}) {
+  const api = withScopeHints(provider);
+  const worker = ownerWorkerName(project, environment);
+  let result;
+  try { result = await api.request('/workers/subdomain'); }
+  catch (error) { if (error.status === 404) throw new Error('workers-subdomain-missing'); throw error; }
+  assert(typeof result?.subdomain === 'string' && result.subdomain, 'workers-subdomain-missing');
+  assert(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(result.subdomain),'invalid-account-subdomain');
+  return {accountId:api.accountId,project,environment,worker,origin:`https://${worker}.${result.subdomain}.workers.dev`};
+}
+
+function entries(declaration, key) {
+  const list = declaration[key] ?? [];
+  assert(Array.isArray(list) && list.every(item => item && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).every(k => ENTRY_KEYS[key].includes(k))), 'invalid-owner-declaration');
+  return list;
+}
+/* RER_DEV_KEY opens local dev identity; it and every key a seed adapter declares
+ * local-only never become a deployed binding, secret or secret source. */
+export const LOCAL_ONLY_KEYS = Object.freeze(['RER_DEV_KEY', 'RER_MODELS_KEY', 'RER_MODELS_SERVICE', '.rer/local/models.json']);
+export function localOnlyBinding(declaration, localOnlyKeys = []) {
+  const refused = new Set([...LOCAL_ONLY_KEYS, ...localOnlyKeys]);
+  const names = [...Object.keys(declaration?.vars ?? {}), declaration?.originVar, ...(Array.isArray(declaration?.secrets) ? declaration.secrets.flatMap(item => [item?.binding, item?.environment]) : [])];
+  return names.find(name => refused.has(name)) ?? null;
+}
+/** A seed declares bindings, never names. Migrations come from the packaged artifact. */
+export function ownerPlan(target, declaration, artifact, { localOnlyKeys = [] } = {}) {
+  assert(declaration?.version === 1 && typeof declaration === 'object' && Object.keys(declaration).every(key => DECLARATION_KEYS.includes(key)), 'invalid-owner-declaration');
+  if (declaration.platforms !== undefined) assert(Array.isArray(declaration.platforms) && declaration.platforms.length > 0 && new Set(declaration.platforms).size === declaration.platforms.length && declaration.platforms.every(item => ['workers','container'].includes(item)), 'invalid-platforms');
+  if (declaration.container !== undefined) {
+    const config=declaration.container;
+    assert(config&&typeof config==='object'&&!Array.isArray(config)&&Object.keys(config).every(key=>['engine','cacheContract','runner','hostVariables','ingress'].includes(key))&&['node','workerd'].includes(config.engine),'invalid-container');
+    if(config.ingress!==undefined)ingressBindings(config.ingress);
+    assert(config.hostVariables===undefined||Array.isArray(config.hostVariables)&&config.hostVariables.every(name=>/^[A-Z][A-Z0-9_]*$/.test(name)),'invalid-container-host-variables');
+    assert(config.cacheContract===undefined||config.cacheContract==='lamp-retained-v1','invalid-container-cache');
+    if(config.runner!==undefined){const runner=config.runner,relative=path=>typeof path==='string'&&!path.startsWith('/')&&path.split('/').every(part=>part&&!['.','..'].includes(part));assert(runner&&Object.keys(runner).every(key=>['entry','files'].includes(key))&&relative(runner.entry)&&Array.isArray(runner.files)&&runner.files.length>0&&runner.files.every(relative),'invalid-container-runner');}
+  }
+  const local = localOnlyBinding(declaration, localOnlyKeys);
+  if (local) throw refuse('local-only-binding', 'binding', local);
+  assert(declaration.project === undefined || declaration.project === target.project, 'owner-project-mismatch');
+  const name = binding => ownerResourceName(target.worker, binding);
+  const d1 = entries(declaration,'d1');
+  assert(artifact.migrations.every(migration => d1.some(item => item.binding === migration.binding)), 'undeclared-migration-binding');
+  const queues = entries(declaration,'queues');
+  for (const item of queues) assert(item.deadLetterQueue === undefined || queues.some(other => other.binding === item.deadLetterQueue), 'invalid-dead-letter-queue');
+  const vars = {...(declaration.vars ?? {})};
+  if (declaration.originVar !== undefined) {
+    assert(identifier(declaration.originVar) && !Object.hasOwn(vars,declaration.originVar), 'invalid-owner-origin-variable');
+    vars[declaration.originVar] = target.origin;
+  }
+  const kv = entries(declaration,'kv').map(({binding}) => ({binding,name:name(binding)}));
+  // A service binding names another project; its Worker name derives from the same environment.
+  const services = entries(declaration,'services').map(({binding,project,entrypoint,allowedHosts,grant}) => ({binding,service:ownerWorkerName(project,target.environment),
+    ...(grant === undefined ? {} : {grant}),...(entrypoint === undefined ? {} : {entrypoint}),...(allowedHosts === undefined ? {} : {props:{allowedHosts}})}));
+  assert(declaration.workersDev === undefined || declaration.workersDev === false, 'invalid-owner-declaration');
+  return validatePlan({version:1,worker:target.worker,compatibilityDate:declaration.compatibilityDate,compatibilityFlags:declaration.compatibilityFlags ?? [],
+    d1:d1.map(({binding}) => ({binding,name:name(binding),migrations:artifact.migrations.filter(x => x.binding === binding).map(({binding:_,...rest}) => rest)})),
+    r2:entries(declaration,'r2').map(item => ({...item,name:name(item.binding)})),
+    ...(kv.length ? {kv} : {}),
+    queues:queues.map(item => ({...item,name:name(item.binding),...(item.deadLetterQueue === undefined ? {} : {deadLetterQueue:name(item.deadLetterQueue)})})),
+    durableObjects:entries(declaration,'durableObjects').map(item => ({...item})),
+    secrets:entries(declaration,'secrets').map(item => ({...item})),
+    crons:[...(declaration.crons ?? [])],vars,
+    // Only declarations using these add the keys, so earlier plans and fingerprints are unchanged.
+    ...(services.length ? {services} : {}),...(declaration.workersDev === false ? {workersDev:false} : {})});
+}
+function assertOwnerNames(target, plan) {
+  assert(plan.worker === target.worker, 'owner-plan-name-mismatch');
+  for (const kind of KINDS) for (const item of resourceKinds[kind].items(plan)) assert(item.name === ownerResourceName(target.worker,item.binding), 'owner-plan-name-mismatch');
+}
+
+function emptyState(target) {
+  return {version:1,kind:STATE_KIND,accountId:target.accountId,project:target.project,environment:target.environment,worker:target.worker,
+    owned:{worker:null,d1:{},r2:{},kv:{},queues:{}},receipt:null};
+}
+export async function readOwnerState(path, target) {
+  let bytes;
+  try { bytes = await regularBytes(path, 4 * 1024 * 1024); }
+  catch (error) { if (error.code === 'ENOENT') return emptyState(target); throw error; }
+  let state; try { state = JSON.parse(bytes); } catch { throw new Error('invalid-owner-state'); }
+  assert(state?.version === 1 && state.kind === STATE_KIND && state.owned && typeof state.owned === 'object'
+    && (state.owned.worker === null || ['pending','created'].includes(state.owned.worker?.status))
+    && KINDS.every(kind => state.owned[kind] && typeof state.owned[kind] === 'object' && Object.values(state.owned[kind]).every(entry => ['pending','created'].includes(entry?.status))), 'invalid-owner-state');
+  assert(state.pendingUpload === undefined || typeof state.pendingUpload?.fingerprint === 'string' && typeof state.pendingUpload?.build === 'string', 'invalid-owner-state');
+  assert(state.accountId === target.accountId && state.project === target.project && state.environment === target.environment && state.worker === target.worker, 'owner-state-target-mismatch');
+  return state;
+}
+async function writeOwnerState(path, state) {
+  await mkdir(dirname(path),{recursive:true,mode:0o700});
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary,JSON.stringify(state,null,2)+'\n',{flag:'wx',mode:0o600});
+  await rename(temporary,path);
+}
+const resourceId = (kind, row) => ({d1:row.uuid,r2:row.creation_date,kv:row.id,queues:row.queue_id})[kind];
+
+function checkResourceIdentity(kind, name, row, entry) {
+  if (row) {
+    if (!entry) throw refuse('resource-name-collision',kind,name);
+    if (entry.status !== 'created') throw refuse('uncertain-resource-create',kind,name);
+    // A state file from before bucket identities were recorded has no id to compare.
+    if ((kind !== 'r2' || entry.id !== undefined) && entry.id !== resourceId(kind,row)) throw refuse('owned-resource-replaced',kind,name);
+  } else if (entry?.status === 'created') throw refuse('owned-resource-missing',kind,name);
+}
+
+/** Read-only: every declared name is either created by this kit or absent. */
+async function ownedResourcesToCreate(api, plan, state) {
+  const create = [];
+  for (const kind of KINDS) {
+    const items = resourceKinds[kind].items(plan);
+    if (!items.length) continue;
+    const rows = await resourceKinds[kind].list(api);
+    for (const item of items) {
+      const row = findResource(rows,kind,item.name);
+      const entry = state.owned[kind][item.name];
+      checkResourceIdentity(kind,item.name,row,entry);
+      if (!row) create.push({kind,item});
+    }
+  }
+  return create;
+}
+/** Re-read every saved resource, including resources omitted from a later plan. */
+async function checkSavedResourceIdentities(api, state) {
+  for (const kind of KINDS) {
+    const entries = Object.entries(state.owned[kind]);
+    if (!entries.length) continue;
+    const rows = await resourceKinds[kind].list(api);
+    for (const [name,entry] of entries) checkResourceIdentity(kind,name,findResource(rows,kind,name),entry);
+  }
+}
+/** Read-only: a bound service Worker must already exist in the account; deploy it first. */
+async function checkServiceWorkers(api, plan) {
+  for (const {service} of plan.services ?? []) if (await workerSettings(api, service) === null) throw refuse('service-worker-missing','service',service);
+}
+async function workerSettings(api, worker) {
+  try { return await api.request(`/workers/scripts/${worker}/settings`); }
+  catch (error) { if (error.status === 404) return null; throw error; }
+}
+/** The fingerprint an upload is about to write, read from its own metadata part. */
+async function uploadFingerprint(body) {
+  const metadata = JSON.parse(await body.get('metadata').text());
+  const fingerprint = deployedFingerprint(metadata);
+  assert(typeof fingerprint === 'string' && fingerprint, 'invalid-upload-metadata');
+  return fingerprint;
+}
+const sameDeployment = (a, b) => a?.versionId === b?.versionId && a?.deploymentId === b?.deploymentId && a?.etag === b?.etag;
+
+/** A completed receipt or the exact identity of an interrupted successful upload proves ownership.
+ * Only the first upload, with no receipt, may recover a lost response by its pending build. */
+async function checkWorkerIdentity(api, plan, artifact, state) {
+  const live = await activeWorker(api, plan.worker);
+  const pending = state.pendingUpload;
+  const expected = pending?.provider ?? state.receipt?.provider;
+  if (expected) {
+    if (!sameDeployment(live, expected)) throw refuse('owned-resource-replaced','worker',plan.worker);
+  } else {
+    const mine = state.owned.worker?.status === 'pending' && pending?.build === hash({plan,artifact}) && pending.fingerprint === deployedFingerprint(live?.settings);
+    if (!mine) throw refuse('uncertain-resource-create','worker',plan.worker);
+  }
+  return live;
+}
+async function checkOwnedWorker(api, plan, artifact, state) {
+  const settings = await workerSettings(api, plan.worker);
+  if (settings === null) {
+    if (state.owned.worker?.status === 'created') throw refuse('owned-resource-missing','worker',plan.worker);
+    return null;
+  }
+  if (!state.owned.worker) throw refuse('resource-name-collision','worker',plan.worker);
+  return checkWorkerIdentity(api, plan, artifact, state);
+}
+
+/** One deploy at a time per state file: an exclusive lock file for the whole run. */
+async function withStateLock(path, run) {
+  await mkdir(dirname(path),{recursive:true,mode:0o700});
+  const lock = `${path}.lock`;
+  let handle;
+  try { handle = await open(lock,'wx',0o600); }
+  catch (error) { throw error.code === 'EEXIST' ? new Error('owner-state-locked') : error; }
+  try {
+    await handle.writeFile(`${process.pid}\n`);
+    await handle.close();
+    return await run();
+  } finally { try { await handle.close(); } finally { await rm(lock,{force:true}); } }
+}
+
+/** Find or create every declared resource under the owner's account, migrate, upload and check health.
+ * Ownership preflight precedes provider writes. A re-run of the same build writes nothing. */
+export async function ownerDeploy({api: provider, target, plan, artifact, statePath, env = {}, fetch = globalThis.fetch, healthOptions = {}, readiness = {}}) {
+  assert(typeof statePath === 'string' && statePath.length, 'missing-owner-state-path');
+  const api = withScopeHints(provider);
+  assert(target?.accountId === api.accountId, 'owner-account-mismatch');
+  validatePlan(plan); assertOwnerNames(target, plan);
+  for (const item of plan.d1) validateMigrations(item.migrations);
+  return withStateLock(statePath, () => deployLocked({api, target, plan, artifact, statePath, env, fetch, healthOptions, readiness}));
+}
+async function deployLocked({api, target, plan, artifact, statePath, env, fetch, healthOptions, readiness}) {
+  const state = await readOwnerState(statePath, target);
+  const save = () => writeOwnerState(statePath, state);
+  await checkServiceWorkers(api, plan);
+  const priorWorker = await checkOwnedWorker(api, plan, artifact, state);
+  const exists = priorWorker !== null;
+  const create = await ownedResourcesToCreate(api, plan, state);
+  if (exists) await checkCronOwnership(api, plan);
+  await secretBindings(api, plan.worker, plan, env, exists);
+  // Record intent before each create. A failed or lost response leaves it pending:
+  // absent on resume means create again; present means an uncertain outcome to inspect.
+  for (const {kind,item} of create) {
+    state.owned[kind][item.name] = {status:'pending'}; await save();
+    const row = await resourceKinds[kind].create(api,item);
+    assert(findResource([row],kind,item.name) === row, 'invalid-created-resource');
+    state.owned[kind][item.name] = {status:'created',...(resourceId(kind,row) === undefined ? {} : {id:resourceId(kind,row)})}; await save();
+  }
+  if (!exists && !state.owned.worker) { state.owned.worker = {status:'pending'}; await save(); }
+  const upload = `/workers/scripts/${plan.worker}?bindings_inherit=strict`;
+  const observed = {...api, async request(path, options) {
+    const sending = path === upload && options?.method === 'PUT';
+    if (sending) {
+      await checkSavedResourceIdentities(api, state);
+      const current = await checkOwnedWorker(api, plan, artifact, state);
+      if (!sameDeployment(priorWorker,current)) throw refuse('owned-resource-replaced','worker',plan.worker);
+      state.pendingUpload = {fingerprint:await uploadFingerprint(options.body),build:hash({plan,artifact})}; await save();
+    }
+    const result = await api.request(path, options);
+    if (sending) {
+      const active = await activeWorker(api, plan.worker);
+      assert(active && deployedFingerprint(active.settings) === state.pendingUpload.fingerprint, 'uploaded-worker-drift');
+      state.pendingUpload.provider = {versionId:active.versionId,deploymentId:active.deploymentId,etag:active.etag};
+      state.owned.worker = {status:'created'}; await save();
+    }
+    return result;
+  }};
+  const receipt = await deploy({api:observed, plan, artifact, artifactSha256:hash(artifact), previousReceipt:state.receipt ?? undefined,
+    createResources:false, uploadWithoutReceipt:true, env, fetch, healthOptions, readiness,
+    onReceipt: async candidate => { if (candidate.changed || !state.receipt) { state.receipt = candidate; delete state.pendingUpload; await save(); } },
+    // Keep each first-health attempt beside the identity it belongs to.
+    onHealth: async candidate => { if (candidate.changed) { state.receipt = candidate; await save(); } }});
+  return {receipt, created:create.map(({kind,item}) => `${kind}:${item.name}`)};
+}
+
+/** Independent read-only health of the last owner deployment recorded in the state file. */
+export async function ownerHealth({api: provider, target, plan, statePath, fetch = globalThis.fetch, healthOptions = {}}) {
+  const api = withScopeHints(provider);
+  validatePlan(plan); assertOwnerNames(target, plan);
+  const state = await readOwnerState(statePath, target);
+  assert(state.receipt, 'missing-owner-receipt');
+  return verifyHealth({...healthOptions, api, plan, receipt:state.receipt, fetch});
+}