@hasna/instructions 0.6.0 → 0.7.0

package/dist/storage/index.js

@@ -0,0 +1,725 @@
+// @bun
+// src/storage/s3-config.ts
+var INSTRUCTIONS_S3_ENV = {
+  bucket: "HASNA_INSTRUCTIONS_S3_BUCKET",
+  prefix: "HASNA_INSTRUCTIONS_S3_PREFIX",
+  region: "HASNA_INSTRUCTIONS_AWS_REGION",
+  endpoint: "HASNA_INSTRUCTIONS_S3_ENDPOINT",
+  forcePathStyle: "HASNA_INSTRUCTIONS_S3_FORCE_PATH_STYLE",
+  accessKeyId: "HASNA_INSTRUCTIONS_S3_ACCESS_KEY_ID",
+  secretAccessKey: "HASNA_INSTRUCTIONS_S3_SECRET_ACCESS_KEY",
+  sessionToken: "HASNA_INSTRUCTIONS_S3_SESSION_TOKEN"
+};
+var INSTRUCTIONS_S3_ALIAS_ENV = {
+  bucket: "INSTRUCTIONS_S3_BUCKET",
+  prefix: "INSTRUCTIONS_S3_PREFIX",
+  region: "INSTRUCTIONS_AWS_REGION",
+  endpoint: "INSTRUCTIONS_S3_ENDPOINT",
+  forcePathStyle: "INSTRUCTIONS_S3_FORCE_PATH_STYLE",
+  accessKeyId: "INSTRUCTIONS_S3_ACCESS_KEY_ID",
+  secretAccessKey: "INSTRUCTIONS_S3_SECRET_ACCESS_KEY",
+  sessionToken: "INSTRUCTIONS_S3_SESSION_TOKEN"
+};
+var BUCKET_PATTERN = /^(?!xn--)[a-z0-9](?:[a-z0-9.-]{1,61}[a-z0-9])?$/;
+var REGION_PATTERN = /^[a-z]{2}(?:-gov)?-[a-z0-9-]+-\d$/;
+var CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+function loadInstructionsS3Config(env = process.env) {
+  const bucket = readEnv(env, "bucket");
+  const configuredWithoutBucket = Object.keys(INSTRUCTIONS_S3_ENV).filter((key) => key !== "bucket").some((key) => readEnv(env, key) !== undefined);
+  if (!bucket) {
+    if (configuredWithoutBucket) {
+      throw new Error(`${INSTRUCTIONS_S3_ENV.bucket} is required when any Instructions S3 setting is configured`);
+    }
+    return;
+  }
+  validateBucket(bucket);
+  const prefix = normalizeInstructionsS3Prefix(readEnv(env, "prefix") ?? "instructions/");
+  const region = readEnv(env, "region") ?? "us-east-1";
+  validateRegion(region);
+  const endpoint = normalizeEndpoint(readEnv(env, "endpoint"));
+  const forcePathStyle = parseBoolean(readEnv(env, "forcePathStyle"), false);
+  const accessKeyId = readEnv(env, "accessKeyId");
+  const secretAccessKey = readEnv(env, "secretAccessKey");
+  const sessionToken = readEnv(env, "sessionToken");
+  if (Boolean(accessKeyId) !== Boolean(secretAccessKey)) {
+    throw new Error(`${INSTRUCTIONS_S3_ENV.accessKeyId} and ${INSTRUCTIONS_S3_ENV.secretAccessKey} must be configured together`);
+  }
+  if (sessionToken && (!accessKeyId || !secretAccessKey)) {
+    throw new Error(`${INSTRUCTIONS_S3_ENV.sessionToken} requires a complete static credential pair`);
+  }
+  return {
+    provider: "s3",
+    bucket,
+    prefix,
+    region,
+    ...endpoint ? { endpoint } : {},
+    forcePathStyle,
+    ...accessKeyId && secretAccessKey ? {
+      credentials: {
+        accessKeyId,
+        secretAccessKey,
+        ...sessionToken ? { sessionToken } : {}
+      }
+    } : {}
+  };
+}
+function normalizeInstructionsS3Prefix(value) {
+  const trimmed = value.trim();
+  if (!trimmed || CONTROL_CHARACTERS.test(trimmed) || trimmed.includes("\\")) {
+    throw new Error("Instructions S3 prefix is invalid");
+  }
+  const withoutEdges = trimmed.replace(/^\/+|\/+$/g, "");
+  if (!withoutEdges || withoutEdges.includes("//")) {
+    throw new Error("Instructions S3 prefix is invalid");
+  }
+  const segments = withoutEdges.split("/");
+  for (const segment of segments) {
+    let decoded;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+      throw new Error("Instructions S3 prefix contains invalid percent encoding");
+    }
+    if (!decoded || decoded === "." || decoded === ".." || decoded.includes("/") || decoded.includes("\\") || CONTROL_CHARACTERS.test(decoded)) {
+      throw new Error("Instructions S3 prefix contains an unsafe path segment");
+    }
+  }
+  return `${segments.join("/")}/`;
+}
+function readEnv(env, key) {
+  const canonical = INSTRUCTIONS_S3_ENV[key];
+  if (Object.prototype.hasOwnProperty.call(env, canonical))
+    return clean(env[canonical]);
+  return clean(env[INSTRUCTIONS_S3_ALIAS_ENV[key]]);
+}
+function clean(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+function parseBoolean(value, fallback) {
+  if (!value)
+    return fallback;
+  switch (value.toLowerCase()) {
+    case "1":
+    case "true":
+    case "yes":
+    case "on":
+      return true;
+    case "0":
+    case "false":
+    case "no":
+    case "off":
+      return false;
+    default:
+      throw new Error("Instructions S3 boolean setting is invalid");
+  }
+}
+function validateBucket(bucket) {
+  if (bucket.length < 3 || bucket.length > 63 || !BUCKET_PATTERN.test(bucket) || bucket.includes("..") || bucket.includes(".-") || bucket.includes("-.") || /^\d{1,3}(?:\.\d{1,3}){3}$/.test(bucket)) {
+    throw new Error("Instructions S3 bucket is invalid");
+  }
+}
+function validateRegion(region) {
+  if (!REGION_PATTERN.test(region))
+    throw new Error("Instructions AWS region is invalid");
+}
+function normalizeEndpoint(value) {
+  if (!value)
+    return;
+  let endpoint;
+  try {
+    endpoint = new URL(value);
+  } catch {
+    throw new Error("Instructions S3 endpoint is invalid");
+  }
+  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new Error("Instructions S3 endpoint must not contain credentials, query parameters, or fragments");
+  }
+  if (endpoint.pathname !== "/") {
+    throw new Error("Instructions S3 endpoint must be an origin without a path");
+  }
+  const localHttp = endpoint.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname);
+  if (endpoint.protocol !== "https:" && !localHttp) {
+    throw new Error("Instructions S3 endpoint must use HTTPS (HTTP is allowed only for loopback development)");
+  }
+  return endpoint.origin;
+}
+// src/storage/s3-object-store.ts
+import { createHash, createHmac } from "crypto";
+var CONTROL_CHARACTERS2 = /[\u0000-\u001f\u007f]/;
+var VERSION_ID_PATTERN = /^[^\u0000-\u001f\u007f]{1,1024}$/;
+var CONDITIONAL_CREATE_ATTEMPTS = 3;
+var DEFAULT_EXISTS_DEADLINE_MS = 5000;
+var DEFAULT_BYTES_DEADLINE_MS = 15000;
+var DEFAULT_STAT_DEADLINE_MS = 5000;
+var DEFAULT_VERSIONED_READ_DEADLINE_MS = 15000;
+var DEFAULT_CONDITIONAL_CREATE_ATTEMPT_DEADLINE_MS = 15000;
+var DEFAULT_EXISTENCE_RECONCILIATION_DEADLINE_MS = 5000;
+var MAX_OPERATION_DEADLINE_MS = 60000;
+var EMPTY_SHA256 = createHash("sha256").update("").digest("hex");
+function resolveOperationDeadlineMs(value, fallback, label) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved <= 0 || resolved > MAX_OPERATION_DEADLINE_MS) {
+    throw new Error(`${label} must be an integer between 1 and ${MAX_OPERATION_DEADLINE_MS} milliseconds`);
+  }
+  return resolved;
+}
+async function runWithDeadline(operation, deadlineMs, onDeadline) {
+  let timer;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      try {
+        onDeadline?.();
+      } finally {
+        reject(new Error("Instructions S3 operation deadline exceeded"));
+      }
+    }, deadlineMs);
+  });
+  try {
+    return await Promise.race([Promise.resolve().then(operation), deadline]);
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
+  }
+}
+function assertSafeInstructionsObjectKey(key) {
+  if (!key || key.length > 1024 || key.startsWith("/") || key.endsWith("/") || key.includes("\\") || CONTROL_CHARACTERS2.test(key)) {
+    throw new Error("Instructions S3 object key is invalid");
+  }
+  for (const segment of key.split("/")) {
+    if (!segment || segment === "." || segment === "..") {
+      throw new Error("Instructions S3 object key contains an unsafe path segment");
+    }
+  }
+}
+function assertSafeInstructionsObjectVersionId(versionId) {
+  if (!VERSION_ID_PATTERN.test(versionId) || versionId.trim() !== versionId) {
+    throw new Error("Instructions S3 object version id is invalid");
+  }
+}
+function createInstructionsS3ObjectStore(config, createClient = (options) => new Bun.S3Client(options), requestFetch = fetch, deadlines = {}) {
+  const existsDeadlineMs = resolveOperationDeadlineMs(deadlines.existsDeadlineMs, DEFAULT_EXISTS_DEADLINE_MS, "Instructions S3 exists deadline");
+  const bytesDeadlineMs = resolveOperationDeadlineMs(deadlines.bytesDeadlineMs, DEFAULT_BYTES_DEADLINE_MS, "Instructions S3 bytes deadline");
+  const statDeadlineMs = resolveOperationDeadlineMs(deadlines.statDeadlineMs, DEFAULT_STAT_DEADLINE_MS, "Instructions S3 stat deadline");
+  const versionedReadDeadlineMs = resolveOperationDeadlineMs(deadlines.versionedReadDeadlineMs, DEFAULT_VERSIONED_READ_DEADLINE_MS, "Instructions S3 versioned read deadline");
+  const conditionalCreateAttemptDeadlineMs = resolveOperationDeadlineMs(deadlines.conditionalCreateAttemptDeadlineMs, DEFAULT_CONDITIONAL_CREATE_ATTEMPT_DEADLINE_MS, "Instructions S3 conditional create attempt deadline");
+  const existenceReconciliationDeadlineMs = resolveOperationDeadlineMs(deadlines.existenceReconciliationDeadlineMs, DEFAULT_EXISTENCE_RECONCILIATION_DEADLINE_MS, "Instructions S3 existence reconciliation deadline");
+  const client = createClient({
+    bucket: config.bucket,
+    region: config.region,
+    ...config.endpoint ? { endpoint: config.endpoint } : {},
+    ...config.credentials ? {
+      accessKeyId: config.credentials.accessKeyId,
+      secretAccessKey: config.credentials.secretAccessKey,
+      ...config.credentials.sessionToken ? { sessionToken: config.credentials.sessionToken } : {}
+    } : {},
+    ...config.forcePathStyle ? { virtualHostedStyle: false } : {}
+  });
+  return {
+    async putIfAbsent(key, bytes, options) {
+      assertSafeInstructionsObjectKey(key);
+      for (let attempt = 1;attempt <= CONDITIONAL_CREATE_ATTEMPTS; attempt += 1) {
+        let response;
+        const controller = new AbortController;
+        try {
+          const url = client.presign(key, { method: "PUT", expiresIn: 60 });
+          response = await runWithDeadline(() => requestFetch(url, {
+            method: "PUT",
+            headers: {
+              "content-type": options.contentType,
+              "content-md5": createHash("md5").update(bytes).digest("base64"),
+              "if-none-match": "*"
+            },
+            body: Uint8Array.from(bytes),
+            redirect: "error",
+            signal: controller.signal
+          }), conditionalCreateAttemptDeadlineMs, () => controller.abort());
+        } catch {
+          let exists = false;
+          try {
+            exists = await runWithDeadline(() => client.file(key).exists(), existenceReconciliationDeadlineMs);
+          } catch {}
+          if (exists)
+            return { status: "existing" };
+          if (attempt < CONDITIONAL_CREATE_ATTEMPTS)
+            continue;
+          throw new Error("Instructions S3 conditional object creation failed");
+        }
+        if (response.ok) {
+          const versionId = cleanResponseVersionId(response.headers.get("x-amz-version-id"));
+          response.body?.cancel().catch(() => {
+            return;
+          });
+          return { status: "created", ...versionId ? { versionId } : {} };
+        }
+        response.body?.cancel().catch(() => {
+          return;
+        });
+        if (response.status === 412)
+          return { status: "existing" };
+        if (response.status === 409 && attempt < CONDITIONAL_CREATE_ATTEMPTS)
+          continue;
+        if (response.status === 409) {
+          throw new Error("Instructions S3 conditional object creation remained conflicted");
+        }
+        throw new Error(`Instructions S3 conditional object creation failed with status ${response.status}`);
+      }
+      throw new Error("Instructions S3 conditional object creation failed");
+    },
+    async get(key, options = {}) {
+      assertSafeInstructionsObjectKey(key);
+      if (options.versionId) {
+        return readExactVersion(config, key, options.versionId, "GET", requestFetch, versionedReadDeadlineMs).then((result) => result?.bytes);
+      }
+      try {
+        const file = client.file(key);
+        const exists = await runWithDeadline(() => file.exists(), existsDeadlineMs);
+        if (!exists)
+          return;
+        return Uint8Array.from(await runWithDeadline(() => file.bytes(), bytesDeadlineMs));
+      } catch {
+        throw new Error("Instructions S3 get operation failed");
+      }
+    },
+    async head(key, options = {}) {
+      assertSafeInstructionsObjectKey(key);
+      if (options.versionId) {
+        return readExactVersion(config, key, options.versionId, "HEAD", requestFetch, versionedReadDeadlineMs).then((result) => result?.metadata);
+      }
+      try {
+        const file = client.file(key);
+        const exists = await runWithDeadline(() => file.exists(), existsDeadlineMs);
+        if (!exists)
+          return;
+        const stat = await runWithDeadline(() => file.stat(), statDeadlineMs);
+        return {
+          size: stat.size,
+          ...stat.etag ? { etag: stat.etag } : {},
+          ...stat.type ? { contentType: stat.type } : {},
+          ...stat.lastModified ? { lastModified: stat.lastModified } : {}
+        };
+      } catch {
+        throw new Error("Instructions S3 head operation failed");
+      }
+    }
+  };
+}
+async function readExactVersion(config, key, versionId, method, requestFetch, deadlineMs) {
+  assertSafeInstructionsObjectVersionId(versionId);
+  const credentials = resolveRequestCredentials(config);
+  const controller = new AbortController;
+  try {
+    const signed = signVersionedRequest(config, key, versionId, method, credentials, new Date);
+    const response = await runWithDeadline(() => requestFetch(signed.url, {
+      method,
+      headers: signed.headers,
+      redirect: "error",
+      signal: controller.signal
+    }), deadlineMs, () => controller.abort());
+    if (response.status === 404) {
+      response.body?.cancel().catch(() => {
+        return;
+      });
+      return;
+    }
+    if (!response.ok) {
+      response.body?.cancel().catch(() => {
+        return;
+      });
+      throw new Error("versioned S3 request failed");
+    }
+    const observedVersionId = cleanResponseVersionId(response.headers.get("x-amz-version-id"));
+    if (observedVersionId !== versionId) {
+      response.body?.cancel().catch(() => {
+        return;
+      });
+      throw new Error("versioned S3 response authority mismatch");
+    }
+    const bytes = method === "GET" ? new Uint8Array(await response.arrayBuffer()) : new Uint8Array;
+    const contentLength = response.headers.get("content-length");
+    const parsedSize = contentLength === null ? bytes.byteLength : Number(contentLength);
+    if (!Number.isSafeInteger(parsedSize) || parsedSize < 0)
+      throw new Error("invalid S3 content length");
+    const lastModifiedValue = response.headers.get("last-modified");
+    const lastModified = lastModifiedValue ? new Date(lastModifiedValue) : undefined;
+    if (lastModified && !Number.isFinite(lastModified.getTime()))
+      throw new Error("invalid S3 last modified timestamp");
+    return {
+      bytes,
+      metadata: {
+        size: parsedSize,
+        versionId: observedVersionId,
+        ...response.headers.get("etag") ? { etag: response.headers.get("etag") } : {},
+        ...response.headers.get("content-type") ? { contentType: response.headers.get("content-type") } : {},
+        ...lastModified ? { lastModified } : {}
+      }
+    };
+  } catch {
+    throw new Error(`Instructions S3 ${method === "GET" ? "get" : "head"} operation failed`);
+  }
+}
+function resolveRequestCredentials(config) {
+  if (config.credentials)
+    return config.credentials;
+  const accessKeyId = process.env.AWS_ACCESS_KEY_ID?.trim();
+  const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY?.trim();
+  const sessionToken = process.env.AWS_SESSION_TOKEN?.trim();
+  if (!accessKeyId || !secretAccessKey) {
+    throw new Error("Instructions S3 exact-version reads require explicit or AWS environment credentials");
+  }
+  return { accessKeyId, secretAccessKey, ...sessionToken ? { sessionToken } : {} };
+}
+function signVersionedRequest(config, key, versionId, method, credentials, now) {
+  const url = buildObjectUrl(config, key);
+  url.searchParams.set("versionId", versionId);
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+  const shortDate = amzDate.slice(0, 8);
+  const headers = new Headers({
+    host: url.host,
+    "x-amz-content-sha256": EMPTY_SHA256,
+    "x-amz-date": amzDate,
+    ...credentials.sessionToken ? { "x-amz-security-token": credentials.sessionToken } : {}
+  });
+  const signedHeaderNames = [
+    "host",
+    "x-amz-content-sha256",
+    "x-amz-date",
+    ...credentials.sessionToken ? ["x-amz-security-token"] : []
+  ].sort();
+  const canonicalHeaders = signedHeaderNames.map((name) => `${name}:${headers.get(name).trim()}
+`).join("");
+  const canonicalQuery = `versionId=${awsEncode(versionId)}`;
+  const canonicalRequest = [
+    method,
+    url.pathname,
+    canonicalQuery,
+    canonicalHeaders,
+    signedHeaderNames.join(";"),
+    EMPTY_SHA256
+  ].join(`
+`);
+  const scope = `${shortDate}/${config.region}/s3/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    scope,
+    createHash("sha256").update(canonicalRequest).digest("hex")
+  ].join(`
+`);
+  const dateKey = hmac(`AWS4${credentials.secretAccessKey}`, shortDate);
+  const regionKey = hmac(dateKey, config.region);
+  const serviceKey = hmac(regionKey, "s3");
+  const signingKey = hmac(serviceKey, "aws4_request");
+  const signature = createHmac("sha256", signingKey).update(stringToSign).digest("hex");
+  headers.set("authorization", `AWS4-HMAC-SHA256 Credential=${credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaderNames.join(";")}, Signature=${signature}`);
+  return { url: url.toString(), headers };
+}
+function buildObjectUrl(config, key) {
+  const encodedKey = key.split("/").map(awsEncode).join("/");
+  if (config.endpoint) {
+    const endpoint = new URL(config.endpoint);
+    if (config.forcePathStyle)
+      endpoint.pathname = `/${awsEncode(config.bucket)}/${encodedKey}`;
+    else {
+      endpoint.hostname = `${config.bucket}.${endpoint.hostname}`;
+      endpoint.pathname = `/${encodedKey}`;
+    }
+    return endpoint;
+  }
+  return config.forcePathStyle ? new URL(`https://s3.${config.region}.amazonaws.com/${awsEncode(config.bucket)}/${encodedKey}`) : new URL(`https://${config.bucket}.s3.${config.region}.amazonaws.com/${encodedKey}`);
+}
+function awsEncode(value) {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function hmac(key, value) {
+  return createHmac("sha256", key).update(value).digest();
+}
+function cleanResponseVersionId(value) {
+  const versionId = value?.trim();
+  if (!versionId || versionId === "null")
+    return;
+  assertSafeInstructionsObjectVersionId(versionId);
+  return versionId;
+}
+function memoryInstructionsObjectStore() {
+  const objects = new Map;
+  let nextVersion = 1;
+  return {
+    async putIfAbsent(key, bytes, options) {
+      assertSafeInstructionsObjectKey(key);
+      const existing = objects.get(key);
+      if (existing)
+        return { status: "existing", versionId: existing.versionId };
+      const versionId = `memory-v${nextVersion++}`;
+      objects.set(key, {
+        bytes: Uint8Array.from(bytes),
+        contentType: options.contentType,
+        lastModified: new Date,
+        versionId
+      });
+      return { status: "created", versionId };
+    },
+    async get(key, options = {}) {
+      assertSafeInstructionsObjectKey(key);
+      if (options.versionId)
+        assertSafeInstructionsObjectVersionId(options.versionId);
+      const object = objects.get(key);
+      if (!object || options.versionId && options.versionId !== object.versionId)
+        return;
+      return Uint8Array.from(object.bytes);
+    },
+    async head(key, options = {}) {
+      assertSafeInstructionsObjectKey(key);
+      if (options.versionId)
+        assertSafeInstructionsObjectVersionId(options.versionId);
+      const object = objects.get(key);
+      return object && (!options.versionId || options.versionId === object.versionId) ? {
+        size: object.bytes.byteLength,
+        contentType: object.contentType,
+        lastModified: new Date(object.lastModified),
+        versionId: object.versionId
+      } : undefined;
+    },
+    keys() {
+      return [...objects.keys()].sort();
+    }
+  };
+}
+// src/storage/s3-backup.ts
+var INSTRUCTIONS_BACKUP_MANIFEST_SCHEMA = "hasna.instructions.backup-object/v1";
+var encoder = new TextEncoder;
+var decoder = new TextDecoder;
+var SHA256_PATTERN = /^[0-9a-f]{64}$/;
+var CONTROL_CHARACTERS3 = /[\u0000-\u001f\u007f]/;
+function buildInstructionsBackupKeys(prefix, backupId) {
+  const normalizedPrefix = normalizeInstructionsS3Prefix(prefix);
+  const encodedBackupId = encodeBackupId(backupId);
+  const rootKey = `${normalizedPrefix}backups/${encodedBackupId}`;
+  const keys = {
+    rootKey,
+    payloadKey: `${rootKey}/payload`,
+    manifestKey: `${rootKey}/manifest.json`
+  };
+  assertSafeInstructionsObjectKey(keys.payloadKey);
+  assertSafeInstructionsObjectKey(keys.manifestKey);
+  return keys;
+}
+async function planInstructionsBackupPush(input) {
+  const keys = buildInstructionsBackupKeys(input.prefix, input.backupId);
+  return {
+    operation: "push",
+    dryRun: true,
+    noNetwork: true,
+    backupId: input.backupId,
+    ...keys,
+    sha256: sha256(input.bytes),
+    sizeBytes: input.bytes.byteLength,
+    contentType: normalizeContentType(input.contentType)
+  };
+}
+async function pushInstructionsBackup(input) {
+  const plan = await planInstructionsBackupPush(input);
+  const existingManifestBytes = await input.store.get(plan.manifestKey);
+  if (existingManifestBytes) {
+    const existingManifest2 = parseManifest(existingManifestBytes, plan, input.backupId);
+    assertManifestMatchesPayload(existingManifest2, input.bytes);
+    const existingPayload2 = await input.store.get(existingManifest2.payloadKey);
+    if (!existingPayload2)
+      throw new Error("Instructions backup payload object is missing");
+    assertBytesMatch(existingPayload2, existingManifest2.sha256, existingManifest2.sizeBytes, "backup payload integrity");
+    return {
+      status: "existing",
+      manifest: existingManifest2,
+      ...await resolveCurrentVersions(input.store, existingManifest2)
+    };
+  }
+  const payloadCreate = await createImmutableObject(input.store, plan.payloadKey, input.bytes, plan.contentType);
+  if (payloadCreate.status === "existing") {
+    const existingPayload2 = await input.store.get(plan.payloadKey);
+    if (!existingPayload2)
+      throw new Error("Instructions backup payload object is missing");
+    assertBytesMatch(existingPayload2, plan.sha256, plan.sizeBytes, "existing immutable payload");
+  }
+  const manifest = {
+    schema: INSTRUCTIONS_BACKUP_MANIFEST_SCHEMA,
+    app: "instructions",
+    backupId: input.backupId,
+    payloadKey: plan.payloadKey,
+    manifestKey: plan.manifestKey,
+    sha256: plan.sha256,
+    sizeBytes: plan.sizeBytes,
+    contentType: plan.contentType,
+    createdAt: normalizeCreatedAt(input.createdAt)
+  };
+  const manifestCreate = await createImmutableObject(input.store, plan.manifestKey, serializeManifest(manifest), "application/json");
+  if (manifestCreate.status === "created") {
+    const versions = completeCreatedVersions(payloadCreate, manifestCreate);
+    return { status: "created", manifest, ...versions ? { versions } : {} };
+  }
+  const racedManifestBytes = await input.store.get(plan.manifestKey);
+  if (!racedManifestBytes)
+    throw new Error("Instructions backup manifest object is missing");
+  const existingManifest = parseManifest(racedManifestBytes, plan, input.backupId);
+  assertManifestMatchesPayload(existingManifest, input.bytes);
+  const existingPayload = await input.store.get(existingManifest.payloadKey);
+  if (!existingPayload)
+    throw new Error("Instructions backup payload object is missing");
+  assertBytesMatch(existingPayload, existingManifest.sha256, existingManifest.sizeBytes, "backup payload integrity");
+  return {
+    status: "existing",
+    manifest: existingManifest,
+    ...await resolveCurrentVersions(input.store, existingManifest)
+  };
+}
+async function pullInstructionsBackup(input) {
+  const versions = normalizeReadVersions(input);
+  const keys = buildInstructionsBackupKeys(input.prefix, input.backupId);
+  const manifestBytes = await input.store.get(keys.manifestKey, versions ? { versionId: versions.manifestVersionId } : undefined);
+  if (!manifestBytes)
+    throw new Error("Instructions backup manifest object is missing");
+  const manifest = parseManifest(manifestBytes, keys, input.backupId);
+  const bytes = await input.store.get(manifest.payloadKey, versions ? { versionId: versions.payloadVersionId } : undefined);
+  if (!bytes)
+    throw new Error("Instructions backup payload object is missing");
+  assertBytesMatch(bytes, manifest.sha256, manifest.sizeBytes, "backup payload integrity");
+  if (versions) {
+    const [manifestMetadata, payloadMetadata] = await Promise.all([
+      input.store.head(keys.manifestKey, { versionId: versions.manifestVersionId }),
+      input.store.head(manifest.payloadKey, { versionId: versions.payloadVersionId })
+    ]);
+    if (manifestMetadata?.versionId !== versions.manifestVersionId || payloadMetadata?.versionId !== versions.payloadVersionId) {
+      throw new Error("Instructions backup immutable version authority check failed");
+    }
+    if (payloadMetadata.size !== manifest.sizeBytes) {
+      throw new Error("Instructions backup payload version size check failed");
+    }
+  }
+  return {
+    manifest,
+    bytes,
+    versionPinned: Boolean(versions),
+    ...versions ? { versions } : {}
+  };
+}
+async function verifyInstructionsBackup(input) {
+  const result = await pullInstructionsBackup(input);
+  return {
+    ok: true,
+    backupId: result.manifest.backupId,
+    payloadKey: result.manifest.payloadKey,
+    manifestKey: result.manifest.manifestKey,
+    sha256: result.manifest.sha256,
+    sizeBytes: result.manifest.sizeBytes,
+    versionPinned: result.versionPinned,
+    ...result.versions ? { versions: result.versions } : {}
+  };
+}
+async function createImmutableObject(store, key, bytes, contentType) {
+  if (!store.putIfAbsent) {
+    throw new Error("Instructions object store does not support atomic immutable creation");
+  }
+  return store.putIfAbsent(key, bytes, { contentType });
+}
+function completeCreatedVersions(payload, manifest) {
+  if (!payload.versionId || !manifest.versionId)
+    return;
+  return { payloadVersionId: payload.versionId, manifestVersionId: manifest.versionId };
+}
+async function resolveCurrentVersions(store, manifest) {
+  const [payload, manifestObject] = await Promise.all([
+    store.head(manifest.payloadKey),
+    store.head(manifest.manifestKey)
+  ]);
+  if (!payload?.versionId || !manifestObject?.versionId)
+    return {};
+  return {
+    versions: {
+      payloadVersionId: payload.versionId,
+      manifestVersionId: manifestObject.versionId
+    }
+  };
+}
+function normalizeReadVersions(input) {
+  const payloadVersionId = input.payloadVersionId?.trim();
+  const manifestVersionId = input.manifestVersionId?.trim();
+  if (Boolean(payloadVersionId) !== Boolean(manifestVersionId)) {
+    throw new Error("Instructions backup payload and manifest version ids must be provided together");
+  }
+  if (!payloadVersionId || !manifestVersionId)
+    return;
+  assertSafeInstructionsObjectVersionId(payloadVersionId);
+  assertSafeInstructionsObjectVersionId(manifestVersionId);
+  return { payloadVersionId, manifestVersionId };
+}
+function encodeBackupId(backupId) {
+  const trimmed = backupId.trim();
+  if (!trimmed || trimmed.length > 128 || trimmed === "." || trimmed === ".." || trimmed.includes("\\") || CONTROL_CHARACTERS3.test(trimmed)) {
+    throw new Error("Instructions backup id is invalid");
+  }
+  return encodeURIComponent(trimmed);
+}
+function normalizeContentType(value) {
+  const contentType = value?.trim() || "application/octet-stream";
+  if (contentType.length > 255 || CONTROL_CHARACTERS3.test(contentType)) {
+    throw new Error("Instructions backup content type is invalid");
+  }
+  return contentType;
+}
+function normalizeCreatedAt(value) {
+  const date = value ?? new Date;
+  if (!Number.isFinite(date.getTime()))
+    throw new Error("Instructions backup creation timestamp is invalid");
+  return date.toISOString();
+}
+function serializeManifest(manifest) {
+  return encoder.encode(`${JSON.stringify(manifest, null, 2)}
+`);
+}
+function parseManifest(bytes, keys, backupId) {
+  let value;
+  try {
+    value = JSON.parse(decoder.decode(bytes));
+  } catch {
+    throw new Error("Instructions backup manifest is not valid JSON");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Instructions backup manifest is invalid");
+  }
+  const manifest = value;
+  if (manifest.schema !== INSTRUCTIONS_BACKUP_MANIFEST_SCHEMA || manifest.app !== "instructions" || manifest.backupId !== backupId || manifest.payloadKey !== keys.payloadKey || manifest.manifestKey !== keys.manifestKey || typeof manifest.sha256 !== "string" || !SHA256_PATTERN.test(manifest.sha256) || typeof manifest.sizeBytes !== "number" || !Number.isSafeInteger(manifest.sizeBytes) || manifest.sizeBytes < 0 || typeof manifest.contentType !== "string" || !manifest.contentType || typeof manifest.createdAt !== "string" || !Number.isFinite(Date.parse(manifest.createdAt))) {
+    throw new Error("Instructions backup manifest failed validation");
+  }
+  assertSafeInstructionsObjectKey(manifest.payloadKey);
+  assertSafeInstructionsObjectKey(manifest.manifestKey);
+  return manifest;
+}
+function assertManifestMatchesPayload(manifest, bytes) {
+  const digest = sha256(bytes);
+  if (manifest.sha256 !== digest || manifest.sizeBytes !== bytes.byteLength) {
+    throw new Error("Instructions backup is immutable; the existing backup id refers to different bytes");
+  }
+}
+function assertBytesMatch(bytes, expectedSha256, expectedSize, label) {
+  if (bytes.byteLength !== expectedSize || sha256(bytes) !== expectedSha256) {
+    throw new Error(`Instructions ${label} check failed`);
+  }
+}
+function sha256(bytes) {
+  return new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+}
+export {
+  verifyInstructionsBackup,
+  pushInstructionsBackup,
+  pullInstructionsBackup,
+  planInstructionsBackupPush,
+  normalizeInstructionsS3Prefix,
+  memoryInstructionsObjectStore,
+  loadInstructionsS3Config,
+  createInstructionsS3ObjectStore,
+  buildInstructionsBackupKeys,
+  assertSafeInstructionsObjectVersionId,
+  assertSafeInstructionsObjectKey,
+  INSTRUCTIONS_S3_ENV,
+  INSTRUCTIONS_S3_ALIAS_ENV,
+  INSTRUCTIONS_BACKUP_MANIFEST_SCHEMA
+};