@pithy-sh/core 0.10.0 → 0.12.0

package/src/migrations/capabilitySets.ts

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MigrationProvider } from "kysely/migration";
+import type { Capability } from "../capability/capability";
+import type { DatabaseSpec } from "../data/databases";
+import { InternalError } from "../error/pithyError";
+import { createMigrationRegistry, type NamespacedMigrations } from "./registry";
+
+/**
+ * **Where a capability's migrations become a registry's sets — one function, composed twice (#729).**
+ *
+ * `pithy migrate` and `pithy doctor` compose these sets from the project on disk; the Worker composes them
+ * from the capabilities it was built with, to answer `GET {basePath}/migrations`. It lived in the CLI until
+ * the Worker needed it too. It reads nothing but `Capability.databases`, so it belongs in core — and if
+ * the two sides composed with two functions, `pithy doctor` and the route could disagree about one
+ * environment with nothing to say which was wrong.
+ */
+
+/**
+ * A retained declaration must name a table this slice declares, beside the migrations that create it.
+ *
+ * A misspelled key would count a table that does not exist, find no rows, and let the `down` through —
+ * the refusal quietly off for the one table it was written for. And retention on a slice with no
+ * migrations has no `down` to be recorded on, so nothing would ever enforce it. Both are an author's mistake,
+ * caught where the declaration is read rather than discovered when a vault is empty (#588).
+ */
+function assertRetainedDeclared(capability: string, database: string, spec: DatabaseSpec): void {
+  const retained = spec.retained ?? [];
+  if (retained.length === 0) return;
+  const unknown = retained.filter((table) => !(table in spec.tables));
+  if (unknown.length > 0) {
+    throw new InternalError({
+      message: `Capability "${capability}" retains ${unknown.map((table) => `"${table}"`).join(", ")} in database "${database}", which its tables do not declare.`,
+      action: "Name tables from that database spec's tables in retained.",
+    });
+  }
+  if (!spec.migrations || Object.keys(spec.migrations).length === 0) {
+    throw new InternalError({
+      message: `Capability "${capability}" retains tables in database "${database}" but ships no migrations for it.`,
+      action: "Declare retained beside the migrations that create those tables.",
+    });
+  }
+}
+
+/**
+ * Every capability's per-database migration set (`DatabaseSpec.migrations`, namespaced by capability
+ * name), in composition order — the raw material {@link buildRegistryFromCapabilities}, the CLI's
+ * fan-out runner and the control-plane seam all build on. The runner needs the sets rather than a
+ * finished provider because two Workers can be bound to one physical D1: their sets merge into a single
+ * ordered provider so that database migrates once, with every Worker's capabilities in it. A Worker
+ * composes only its own, which is why the seam's `undeclared` is relative to that Worker. Migrations
+ * without a `migrationOrder` fail here, attributed to their capability.
+ */
+export function collectMigrationSets(capabilities: Capability[]): NamespacedMigrations[] {
+  const sets: NamespacedMigrations[] = [];
+  for (const capability of capabilities) {
+    for (const [database, spec] of Object.entries(capability.databases ?? {})) {
+      assertRetainedDeclared(capability.name, database, spec);
+      if (!spec.migrations) continue;
+      if (spec.migrationOrder === undefined) {
+        throw new InternalError({
+          message: `Capability "${capability.name}" has migrations for database "${database}" but no migrationOrder.`,
+          action: "Set migrationOrder on that database spec (core low, app high).",
+        });
+      }
+      sets.push({
+        database,
+        namespace: capability.name,
+        order: spec.migrationOrder,
+        migrations: spec.migrations,
+        ...(spec.retained && spec.retained.length > 0 ? { retained: spec.retained } : {}),
+      });
+    }
+  }
+  return sets;
+}
+
+/**
+ * Compose every capability's per-database migration sets (`DatabaseSpec.migrations`,
+ * namespaced by capability name) into one ordered provider per database. A database
+ * nobody migrates gets no provider; migrations without a `migrationOrder` fail here,
+ * attributed to their capability.
+ */
+export function buildRegistryFromCapabilities(capabilities: Capability[]): Record<string, MigrationProvider> {
+  return createMigrationRegistry(collectMigrationSets(capabilities));
+}

package/src/migrations/registry.ts

@@ -62,6 +62,51 @@ function assertValidLocalKey(localKey: string, namespace: string): void {
   }
 }
 
+/**
+ * The composed key for one of a set's migrations: `NNNN_<namespace>_<localKey>`. The one place the shape is
+ * written, so the registry and anything naming a declared migration's namespace build the same string.
+ */
+export function composedMigrationKey(set: Pick<NamespacedMigrations, "order" | "namespace">, localKey: string): string {
+  return `${String(set.order).padStart(ORDER_DIGITS, "0")}_${set.namespace}_${localKey}`;
+}
+
+/** A composed key taken back apart: the three parts {@link createMigrationRegistry} joined. */
+export interface ComposedMigrationKey {
+  /** The capability's `migrationOrder` — the zero-padded prefix, as a number. */
+  order: number;
+  /** The capability namespace — its `name`, which the manifest reports beside every capability. */
+  namespace: string;
+  /** The capability's own stable key, e.g. `0001_init`. */
+  localKey: string;
+}
+
+/**
+ * The composed key shape, anchored at both ends: the order prefix, a namespace (which admits no separator,
+ * so the first underscore after it is the boundary), then a local key, which may hold any number.
+ */
+const COMPOSED_KEY_PATTERN = new RegExp(
+  `^(\\d{${ORDER_DIGITS}})_(${NAMESPACE_PATTERN.source.slice(1, -1)})_(${LOCAL_KEY_PATTERN.source.slice(1, -1)})$`,
+);
+
+/**
+ * Take a composed key back apart — the inverse of the composition below.
+ *
+ * A declared migration's namespace is known from the set it came from. An **undeclared** one — applied in
+ * the database, carried by no provider this build composes — has nothing but its key, so this is the only
+ * way to say whose it was. **Null for a key no registry could have composed**, a migration written by hand
+ * or by another tool: guessing a namespace for it would be inventing one.
+ *
+ * The patterns are the same constants the composition enforces, so the two cannot disagree about what a
+ * key looks like.
+ */
+export function decomposeMigrationKey(key: string): ComposedMigrationKey | null {
+  const match = COMPOSED_KEY_PATTERN.exec(key);
+  if (!match) return null;
+  const [, order, namespace, localKey] = match;
+  if (order === undefined || namespace === undefined || localKey === undefined) return null;
+  return { order: Number(order), namespace, localKey };
+}
+
 /** Merge one database's sets into a provider, enforcing the per-database invariants. */
 function composeDatabase(database: string, sets: NamespacedMigrations[]): MigrationProvider {
   const seenOrders = new Set<number>();
@@ -85,10 +130,9 @@ function composeDatabase(database: string, sets: NamespacedMigrations[]): Migrat
 
   const composed: Record<string, Migration> = {};
   for (const set of [...sets].sort((a, b) => a.order - b.order)) {
-    const prefix = String(set.order).padStart(ORDER_DIGITS, "0");
     for (const localKey of Object.keys(set.migrations).sort()) {
       const migration = set.migrations[localKey];
-      if (migration) composed[`${prefix}_${set.namespace}_${localKey}`] = migration;
+      if (migration) composed[composedMigrationKey(set, localKey)] = migration;
     }
   }
 

package/src/migrations/state.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { MigrationProvider } from "kysely/migration";
+import { appliedMigrationChain, migrationKysely } from "./bookkeeping";
+import { readGroupPosition, readMigrationGroups } from "./groups";
+import { readMigrationLedger } from "./runner";
+
+/**
+ * **Where one database stands, read in one place (#729).**
+ *
+ * The control-plane seam answers `GET {basePath}/migrations` from this: what is applied, what this build
+ * declares and the database lacks, what the database holds and this build no longer declares, and which
+ * run put it there. Each half already had a reader — {@link readMigrationLedger} for both directions,
+ * {@link readMigrationGroups} and {@link readGroupPosition} for the group (#694) — and this composes them
+ * rather than reading either table a second way.
+ *
+ * Read-only. It applies nothing, creates nothing, and reverses nothing: a screen somebody opened to *ask*
+ * must not be the thing that changes the schema.
+ */
+
+/** Whether the last group can still be taken back by name — {@link readGroupPosition}, minus `absent`. */
+export type MigrationGroupStanding =
+  | {
+      /** The group's migrations are the contiguous tip of this ledger. The CLI's rollback has refusals of its own. */
+      state: "top";
+    }
+  | {
+      /** Something sits over the group or inside it, so reversing it by name is refused. */
+      state: "buried";
+      /** The groups in the way, newest first. */
+      above: string[];
+      /** The migrations in the way that no group claims, newest first. */
+      ungrouped: string[];
+    };
+
+/** The newest group with anything still applied here, and whether it is still reversible. */
+export interface MigrationLastGroup {
+  /** The group's value — what `--rollback --group` takes. */
+  group: string;
+  /** When it last applied something here. */
+  appliedAt: Date;
+  /** What it applied here and is still applied, in application order. */
+  migrations: string[];
+  /** Whether it is the tip of the chain, or what is in its way. */
+  position: MigrationGroupStanding;
+}
+
+/** One database's migration state. */
+export interface MigrationState {
+  /** Every applied migration, in the order the ledger applied them. */
+  applied: string[];
+  /** Declared and not yet applied, in the order they would run. */
+  pending: string[];
+  /** Applied and not declared by this build, sorted. Kysely refuses the whole chain on any one of these. */
+  undeclared: string[];
+  /** The newest group with anything applied here, or null when nothing applied here was ever grouped. */
+  lastGroup: MigrationLastGroup | null;
+}
+
+/**
+ * Read one database's migration state against the provider this build composes for it.
+ *
+ * **The last group is the newest one with something still applied.** Group rows are forgotten as their
+ * migrations come down, so this is ordinarily the newest group recorded. A group whose rows outlived their
+ * ledger rows reads as `absent` and is passed over: naming it as where the environment stands would name a
+ * release that is no longer in the database.
+ */
+export async function readMigrationState(database: D1Database, provider: MigrationProvider): Promise<MigrationState> {
+  const { pending, undeclared } = await readMigrationLedger(database, provider);
+  const applied = await appliedMigrationChain(migrationKysely(database));
+  return { applied, pending, undeclared, lastGroup: await lastGroupOf(database, applied) };
+}
+
+/** Walk the groups newest first and stop at the first one this database still holds any of. */
+async function lastGroupOf(database: D1Database, applied: readonly string[]): Promise<MigrationLastGroup | null> {
+  const held = new Set(applied);
+  const groups = await readMigrationGroups(database);
+  for (const group of [...groups].reverse()) {
+    const position = await readGroupPosition(database, group.group);
+    if (position.state === "absent") continue;
+    return {
+      group: group.group,
+      appliedAt: group.appliedAt,
+      migrations: group.migrations.filter((name) => held.has(name)),
+      position:
+        position.state === "top"
+          ? { state: "top" }
+          : { state: "buried", above: position.above, ungrouped: position.ungrouped },
+    };
+  }
+  return null;
+}

package/src/naming/feature.ts

@@ -34,11 +34,26 @@ import { assertValidProjectName, kebab } from "./resource";
  * implementation rather than two that drift.
  */
 
-/** A Cloudflare resource kind a feature can provision. All two characters — `MAX_FEATURE_KIND` in `./limits`. */
-export type FeatureResourceKind = "d1" | "kv" | "r2";
+/** A Cloudflare resource kind Pithy names and creates — in a feature, and in every declared environment. */
+export type FeatureResourceKind = "d1" | "kv" | "r2" | "queue";
 
 /** Every feature resource kind, for tests and for callers that enumerate. */
-export const FEATURE_RESOURCE_KINDS: readonly FeatureResourceKind[] = ["d1", "kv", "r2"];
+export const FEATURE_RESOURCE_KINDS: readonly FeatureResourceKind[] = ["d1", "kv", "r2", "queue"];
+
+/**
+ * **The segment each kind ends a feature resource's name with — never more than `MAX_FEATURE_KIND` (#662).**
+ *
+ * `d1`, `kv` and `r2` spell themselves. A queue is `q`, and that is load-bearing: `MAX_FEATURE_KIND` is a term in
+ * `FEATURE_DERIVED_PROJECT_NAME`, so spelling it `queue` would take the project budget from 26 to 23 — and a
+ * project name is stable forever once anything is provisioned, so a smaller budget orphans every resource of a
+ * project already named against the old one. `feature.test.ts` fails on a segment longer than the budget.
+ */
+export const FEATURE_KIND_SEGMENT: Readonly<Record<FeatureResourceKind, string>> = {
+  d1: "d1",
+  kv: "kv",
+  r2: "r2",
+  queue: "q",
+};
 
 /** The identity of a feature — everything a feature name is derived from. */
 export interface FeatureIdentity {
@@ -292,10 +307,11 @@ export function assertFeatureSlugFits(identity: FeatureIdentity, shapes: readonl
 }
 
 /**
- * The full Cloudflare resource name for a feature's binding — `<project>-f<issue>-<slug>--<binding>-<kind>`.
+ * The full Cloudflare resource name for a feature's binding — `<project>-f<issue>-<slug>--<binding>-<kind>`, the
+ * kind spelled by {@link FEATURE_KIND_SEGMENT}.
  *
- * Held to **R2's 63**, the strictest of the three kinds a feature provisions, so one shape is legal for
- * all of them: lowercase, hyphenated, alphanumeric at both ends. A D1 or KV name could be longer, but a
+ * Held to **R2's 63**, the strictest of the kinds a feature provisions and a queue's number too, so one shape is
+ * legal for all of them: lowercase, hyphenated, alphanumeric at both ends. A D1 or KV name could be longer, but a
  * feature that provisions a bucket and a database wants them recognizably the same name.
  */
 export function featureResourceName(identity: FeatureIdentity, binding: string, kind: FeatureResourceKind): string {
@@ -303,7 +319,7 @@ export function featureResourceName(identity: FeatureIdentity, binding: string,
     identity,
     kebab(identity.slug),
     kebab(binding),
-    `-${kind}`,
+    `-${FEATURE_KIND_SEGMENT[kind]}`,
     NAMESPACE_LIMITS.r2.maxLength,
     NAMESPACE_LIMITS.r2.label,
   );
@@ -364,6 +380,29 @@ export function featureWorkerName(identity: FeatureIdentity, app: string): strin
   );
 }
 
+/** The `<thing>` a feature's Artifacts namespace ends with, after {@link FEATURE_TAIL_SEPARATOR} (#673). */
+export const FEATURE_ARTIFACTS_THING = "artifacts";
+
+/**
+ * A feature's **Artifacts namespace** — `<project>-f<issue>-<slug>--artifacts` (#673).
+ *
+ * A declared environment's namespace is `<project>-<env>` and has no `<thing>`. A feature's needs one, because the
+ * separator and what follows it are what make a name a feature name: {@link isFeatureOwnedName} reads this one back
+ * as this feature's, so `pithy feature destroy` reaps the repos of exactly this branch and of no sibling. Held to the
+ * namespace's 63, the same number the rest of a feature's names are derived against, and `artifacts` is shorter than
+ * the shortest binding tail, so it moves no slug budget.
+ */
+export function featureArtifactsNamespace(identity: FeatureIdentity): string {
+  return composeFeatureName(
+    identity,
+    kebab(identity.slug),
+    FEATURE_ARTIFACTS_THING,
+    "",
+    NAMESPACE_LIMITS.artifactsNamespace.maxLength,
+    NAMESPACE_LIMITS.artifactsNamespace.label,
+  );
+}
+
 /**
  * The deployed name of one of a feature's **Workflows** — `<project>-f<issue>-<slug>--<capability>-<job>` (#643).
  *

package/src/naming/limits.ts

@@ -107,6 +107,35 @@ export const NAMESPACE_LIMITS = {
    * no longer hashes one at 63.
    */
   kv: { label: "a KV namespace title", maxLength: 512, minLength: 1, policy: "truncate", source: "cloudflare" },
+  /**
+   * A Queue name: **1 to 63 characters**, lowercase letters, digits and dashes, starting and ending with a letter
+   * or number ([Queues · Get started](https://developers.cloudflare.com/queues/get-started/), verified
+   * 2026-10-18). Truncated rather than refused: Pithy recomputes a queue's name from its binding on every run,
+   * as it does a bucket's, so a deterministic hash is safe (#662). The same 63 as R2, so a feature's queue fits
+   * the shape {@link FEATURE_DERIVED_PROJECT_NAME} is derived against and moves no budget.
+   */
+  queue: { label: "a Queue name", maxLength: 63, minLength: 1, policy: "truncate", source: "cloudflare" },
+  /**
+   * An Artifacts namespace: **2 to 63 characters**, starting with a letter or digit, the rest letters, digits, `.`,
+   * `_` and `-` ([Artifacts · Limits](https://developers.cloudflare.com/artifacts/platform/limits/), verified
+   * 2026-10-18). Truncated rather than refused: the kit derives it from the project and the environment on every
+   * run, like an R2 bucket name, and the longest project and environment compose 34 characters, so it never is (#673).
+   */
+  artifactsNamespace: {
+    label: "an Artifacts namespace name",
+    maxLength: 63,
+    minLength: 2,
+    policy: "truncate",
+    source: "cloudflare",
+  },
+  /**
+   * An Artifacts repo name. **The charset is Cloudflare's** — a letter or digit, then letters, digits, `.`, `_` and
+   * `-` ([Artifacts · Limits](https://developers.cloudflare.com/artifacts/platform/limits/), verified 2026-10-18) —
+   * and **the length is ours**: that page states one for a namespace and none for a repo, so 2 to 63 mirrors the
+   * namespace rather than inventing a second number. Refused, never truncated: a repo name is either a UUID or a
+   * name somebody chose, and a name somebody chose is never silently shortened (#673).
+   */
+  artifactsRepo: { label: "an Artifacts repo name", maxLength: 63, minLength: 2, policy: "refuse", source: "pithy" },
   /**
    * A D1 database name: `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` in the OpenAPI schema, and **no documented
    * length cap** — the limits page has no row for it. So the ceiling here is {@link MAX_PITHY_NAME}.
@@ -196,7 +225,10 @@ export const FEATURE_TAIL_SEPARATOR = "--";
  */
 export const MIN_VERBATIM_BINDING = 12;
 
-/** The longest feature resource kind — `d1`, `kv`, `r2` are all two characters. `feature.test.ts` pins it. */
+/**
+ * The longest feature resource kind segment — `d1`, `kv`, `r2`, and a queue's `q` (#662). `feature.test.ts` pins
+ * every kind's `FEATURE_KIND_SEGMENT` to it, so a longer segment fails rather than shrinking every project's budget.
+ */
 export const MAX_FEATURE_KIND = 2;
 
 /**
@@ -217,7 +249,7 @@ export const WORKFLOW_DERIVED_PROJECT_NAME =
 
 /**
  * What the longest feature resource name leaves a project — `<project>-f<issue>-<slug>--<binding>-<kind>`,
- * against R2's 63 (the strictest of the three kinds a feature provisions, and the same number a
+ * against R2's 63 (the strictest of the kinds a feature provisions, a queue's number too, and the same number a
  * feature Worker script gets).
  *
  * ```
@@ -226,7 +258,7 @@ export const WORKFLOW_DERIVED_PROJECT_NAME =
  *   -  6   the issue number, six digits — `f999999` (MAX_ISSUE_DIGITS)
  *   - 12   `-` + a legible slug (MIN_LEGIBLE_SLUG)
  *   - 14   `--` + a binding kept whole (FEATURE_TAIL_SEPARATOR, MIN_VERBATIM_BINDING)
- *   -  3   `-` + the kind, `d1` | `kv` | `r2`
+ *   -  3   `-` + the kind, `d1` | `kv` | `r2` | `q`
  *   ----
  *     26
  * ```

package/src/naming/provisionScope.ts

@@ -8,6 +8,7 @@ import { assertValidEnvironment, FEATURE_ENVIRONMENT, GLOBAL_SCOPE, isFeatureMar
 import {
   type FeatureIdentity,
   type FeatureResourceKind,
+  featureArtifactsNamespace,
   featureResourceName,
   featureSecretEntryName,
   featureWorkerName,
@@ -189,10 +190,21 @@ export interface ProvisionScope {
    * `<project>-feature-email-send` would be one Workflow every open branch deployed over every other's.
    */
   readonly workflowHost: Omit<WorkflowHostNameParts, "capability">;
+  /**
+   * The Artifacts namespace an `artifacts` binding names in this scope (#673): `<project>-<env>` in a declared
+   * environment, `<project>-f<issue>-<slug>--artifacts` in a feature. On the scope for the reason every other name
+   * is: the stanza a run writes and the namespace it writes into it are one decision.
+   */
+  readonly artifactsNamespace: string;
 }
 
 /** The wrangler binding array a resource kind's name is composed for. */
-const KIND_NAMER: Record<FeatureResourceKind, "d1" | "kv" | "r2"> = { d1: "d1", kv: "kv", r2: "r2" };
+const KIND_NAMER: Record<FeatureResourceKind, "d1" | "kv" | "r2" | "queue"> = {
+  d1: "d1",
+  kv: "kv",
+  r2: "r2",
+  queue: "queue",
+};
 
 /**
  * The one branch every scope shares: a `global` secret resolves to the project's single
@@ -345,6 +357,7 @@ export function environmentScope(project: string, environment: string): Provisio
     secretEntry: (secret, secretScope) =>
       secretEntryName(project, secret, secretScope, () => names.secretEntry(secret)),
     workflowHost: { project, env: environment },
+    artifactsNamespace: names.artifactsNamespace(),
   };
 }
 
@@ -392,6 +405,11 @@ export function featureScope(identity: FeatureIdentity): ProvisionScope {
     secretEntry: (secret) => featureSecretEntryName(identity, secret),
     // `env` is the stanza — what the host's `ENVIRONMENT` var says — and `feature` is what its names take.
     workflowHost: { project: identity.project, env: FEATURE_ENVIRONMENT, feature: identity },
+    // The feature's own, read back as its own by `isFeatureOwnedName`, so teardown reaps no sibling's repos. A
+    // getter, so a slug too long for it refuses where the namespace is asked for, never where the scope is made.
+    get artifactsNamespace() {
+      return featureArtifactsNamespace(identity);
+    },
   };
 }
 

package/src/naming/resourceNames.ts

@@ -4,7 +4,13 @@
 import { InternalError, ValidationError } from "../error/pithyError";
 import { workflowHostName, workflowScriptName } from "../workflow/naming";
 import { assertValidEnvironment, GLOBAL_SCOPE } from "./environment";
-import { type FeatureIdentity, type FeatureResourceKind, featureResourceName, featureWorkerName } from "./feature";
+import {
+  type FeatureIdentity,
+  type FeatureResourceKind,
+  featureArtifactsNamespace,
+  featureResourceName,
+  featureWorkerName,
+} from "./feature";
 import { NAMESPACE_LIMITS, type NamespaceLimit } from "./limits";
 import { assertValidProjectName, kebab, resourceName } from "./resource";
 
@@ -57,6 +63,8 @@ export interface ScopedNames {
   kv(binding: string): string;
   /** An R2 bucket. Cloudflare's 63 — the one namespace where that number was always right. */
   r2(binding: string): string;
+  /** A Queue. Cloudflare's 63, truncated with a stable hash like a bucket (#662). */
+  queue(binding: string): string;
   /** A Vectorize index. 64 bytes, refused rather than truncated: a renamed index has no vectors. */
   vectorizeIndex(index: string): string;
   /** A Secrets Store entry. No Cloudflare cap; Pithy's ceiling. */
@@ -65,15 +73,33 @@ export interface ScopedNames {
   apiToken(profile: string): string;
 }
 
+/**
+ * The names in one declared environment: everything a scope has, and the one name that exists per environment
+ * and never at `global`.
+ */
+export interface EnvironmentNames extends ScopedNames {
+  /**
+   * The Artifacts namespace — `<project>-<env>`, with no `<thing>` (#673). One per environment, so a feature's
+   * repos never sit beside production's and the per-namespace rate limit splits per environment. There is no
+   * global one, because a namespace shared across environments is exactly that mix.
+   */
+  artifactsNamespace(): string;
+}
+
 /** The names a feature environment provisions under, with the project already bound. */
 export interface FeatureNames {
-  /** A feature's D1, KV, or R2 resource — `<project>-f<issue>-<slug>-<binding>-<kind>`. */
+  /** A feature's D1, KV, R2 or Queue resource — `<project>-f<issue>-<slug>--<binding>-<kind>`. */
   resource(binding: string, kind: FeatureResourceKind): string;
   /**
    * A feature's Worker script — `<project>-f<issue>-<slug>-<app>`, from the `apps/<app>` directory and
    * never the deploy name, which already leads with the project (#587).
    */
   worker(app: string): string;
+  /**
+   * A feature's Artifacts namespace — `<project>-f<issue>-<slug>--artifacts` (#673). The tail is what makes it a
+   * feature name `isFeatureOwnedName` reads back, so teardown reaps this feature's repos and no sibling's.
+   */
+  artifactsNamespace(): string;
 }
 
 /** Everything a project can be asked to name. Created once, from the project, by {@link resourceNames}. */
@@ -81,7 +107,7 @@ export interface ProjectNames {
   /** The kebabbed project name every name below leads with. */
   readonly project: string;
   /** The names in one environment. Throws if the environment is not one this scheme accepts. */
-  env(environment: string): ScopedNames;
+  env(environment: string): EnvironmentNames;
   /** The names shared by every environment — the `global` scope, without typing the word. */
   readonly global: ScopedNames;
   /** The names a feature environment provisions under. */
@@ -134,6 +160,22 @@ function scopedName(project: string, scope: string, thing: string, limit: Namesp
   return name;
 }
 
+/**
+ * `<project>-<env>`, under the Artifacts namespace rule. The project and environment are both validated by now, and
+ * the longest of each compose 34 characters, so the cap is a check rather than a truncation that ever happens.
+ */
+function artifactsNamespaceName(project: string, environment: string): string {
+  const limit = NAMESPACE_LIMITS.artifactsNamespace;
+  const name = `${project}-${environment}`;
+  if (name.length > limit.maxLength || name.length < limit.minLength) {
+    throw new InternalError({
+      message: `"${name}" does not fit ${limit.label}, which takes ${limit.minLength} to ${limit.maxLength} characters.`,
+      action: "Shorten the project or environment name.",
+    });
+  }
+  return name;
+}
+
 /** The getters for one scope. `global` and every environment share this, so nothing special-cases either. */
 function scopedNames(project: string, scope: string): ScopedNames {
   return {
@@ -142,6 +184,7 @@ function scopedNames(project: string, scope: string): ScopedNames {
     d1: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.d1),
     kv: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.kv),
     r2: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.r2),
+    queue: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.queue),
     vectorizeIndex: (index) => scopedName(project, scope, index, NAMESPACE_LIMITS.vectorizeIndex),
     secretEntry: (secret) => scopedName(project, scope, secret, NAMESPACE_LIMITS.secretEntry),
     apiToken: (profile) => scopedName(project, scope, profile, NAMESPACE_LIMITS.apiToken),
@@ -161,9 +204,12 @@ export function resourceNames(project: string): ProjectNames {
 
   return {
     project: normalized,
-    env(environment: string): ScopedNames {
+    env(environment: string): EnvironmentNames {
       assertValidEnvironment(environment);
-      return scopedNames(normalized, environment);
+      return {
+        ...scopedNames(normalized, environment),
+        artifactsNamespace: () => artifactsNamespaceName(normalized, environment),
+      };
     },
     global: scopedNames(normalized, GLOBAL_SCOPE),
     feature(identity): FeatureNames {
@@ -171,6 +217,7 @@ export function resourceNames(project: string): ProjectNames {
       return {
         resource: (binding, kind) => featureResourceName(full, binding, kind),
         worker: (app) => featureWorkerName(full, app),
+        artifactsNamespace: () => featureArtifactsNamespace(full),
       };
     },
   };

package/src/privacy/blindIndex.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type EncryptionConfig, keyBytes } from "../crypto/envelope";
+import { FIELD_KEYS_BINDING } from "../crypto/fieldKeys";
+import { type BlindIndexNormalizer, normalizeForIndex } from "./encrypted";
+
+/**
+ * **A blind index: a keyed hash an encrypted column can be found by** (#390).
+ *
+ * An encrypted column cannot answer `WHERE email = ?`. A sibling column holding `HMAC(key, normalize(value))` can,
+ * for equality and nothing else. One rule here is shared by the app Worker that seals, `sealed().match` that looks
+ * up, and the rotator that re-indexes inside the manager, so the three cannot hash one value two ways.
+ *
+ * - **The key is derived, on the field key's own version axis.** Each version's index key is HKDF-SHA256 over that
+ *   version's field key, with the label `pithy/blind-index/<normalizer>`. One secret, one rotation.
+ * - **The value carries its version**: `<version>:<hmac>`, so the stale count reaches an index exactly as it reaches
+ *   an envelope, by reading the prefix.
+ * - **The normalizer is in the label**, so changing a field's normalizer cannot silently miss against old hashes: they
+ *   are hashes under a different key, and the change reads as a re-index.
+ */
+
+/** The HKDF label one normalizer's index keys are derived under. */
+export function blindIndexLabel(normalizer: BlindIndexNormalizer): string {
+  return `pithy/blind-index/${normalizer}`;
+}
+
+/** Unpadded base64url, the alphabet a blind index is written in. */
+function base64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** The HMAC key for one version and normalizer: HKDF-SHA256 over that version's field key. */
+export async function blindIndexKey(
+  config: EncryptionConfig,
+  version: number,
+  normalizer: BlindIndexNormalizer,
+): Promise<CryptoKey> {
+  const material = await crypto.subtle.importKey(
+    "raw",
+    keyBytes(config, version, { keys: FIELD_KEYS_BINDING }),
+    "HKDF",
+    false,
+    ["deriveBits"],
+  );
+  const bits = await crypto.subtle.deriveBits(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: new Uint8Array(0),
+      info: Uint8Array.from(new TextEncoder().encode(blindIndexLabel(normalizer))),
+    },
+    material,
+    256,
+  );
+  return crypto.subtle.importKey("raw", bits, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+}
+
+/** The blind index of `value` under `version`: `<version>:<hmac>`. The value is normalized first. */
+export async function blindIndexValue(
+  config: EncryptionConfig,
+  version: number,
+  normalizer: BlindIndexNormalizer,
+  value: string,
+): Promise<string> {
+  const key = await blindIndexKey(config, version, normalizer);
+  const mac = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    Uint8Array.from(new TextEncoder().encode(normalizeForIndex(normalizer, value))),
+  );
+  return `${version}:${base64Url(new Uint8Array(mac))}`;
+}
+
+/** The version a blind-index value was written under, or `null` for a value that is not one. */
+export function blindIndexVersion(value: string): number | null {
+  const match = /^(\d+):/.exec(value);
+  return match ? Number(match[1]) : null;
+}