@ultimat3/core 25.0.0 → 25.2.0

package/README.md

@@ -11,6 +11,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the one lazy `AsyncLocalStorage`, every ambient scope in the framework | `async-context.ts` |
 | request context on that seam | `context.ts` |
 | `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` |
+| whether a permission grant reaches a name — `grantCovers`, `*` and `<prefix>:*` | `actor.ts` |
 | acting as another actor, with an origin and a reason | `impersonate.ts` |
 | is an error worth retrying? one classification per code | `error-retry.ts` |
 | how long to wait before the next attempt — one curve, one jitter table | `backoff.ts` |
@@ -495,6 +496,16 @@ match with `sealAll()`; uniqueness cannot be held across keys.
   before trusting an empty `checks`.
 - Anything that opens a socket calls `markListening(server.url.origin)` and releases it on close.
   That is what tells the sealed test network a loopback request is this process, not egress.
+- **A live suite's throwaway database is named by `probeDatabaseName(prefix)`** — test support,
+  here because tier 0 is the one tier every package with a live suite can import. Prefix, pid,
+  creation second (base 36), eight random hex characters, at most `PROBE_DATABASE_NAME_MAX` (63) bytes, valid unquoted: a
+  fixed name let two runs against one server drop each other's database.
+  `bun run probe-databases` refuses `create database` on any other name (`X_PROBE_DATABASE_FIXED`).
+  A killed run never reaches its `afterAll`, so call `sweepProbeDatabases(executor, PROBE_DB)`
+  before the `create`: it drops the same prefix's probe databases whose pid is dead on this host
+  AND which no backend is connected to AND whose creation second, carried in the name, is older than
+  `PROBE_DATABASE_MIN_AGE_MS` (10 minutes) — a concurrent run on any host is left alone, even between
+  its `create` and its first connection.
 
 ## Metrics: same seam as tracing, one signal over
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "25.0.0",
+  "version": "25.2.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "25.0.0"
+    "@ultimat3/schema": "25.2.0"
   }
 }

package/src/actor.ts

@@ -202,6 +202,18 @@ export function hasScope(actor: Actor, scope: string): boolean {
   return actor.scopes.includes(scope);
 }
 
+/**
+ * Whether one permission grant reaches `wanted`: `*` reaches everything, `<prefix>:*` every name
+ * beginning `<prefix>:` (any depth), anything else only itself. The PREFIX, never the first
+ * segment: `billing:invoice:*` read as "all of `billing`" granted refunds to an invoice clerk.
+ * Here, at tier 0, because `@ultimat3/policy` (`can()`) and `@ultimat3/auth` (an API key's cut
+ * to its owner) are one tier and may not share a copy — two copies were how it drifted.
+ */
+export function grantCovers(grant: string, wanted: string): boolean {
+  if (grant === '*' || grant === wanted) return true;
+  return grant.endsWith(':*') && wanted.startsWith(grant.slice(0, -1));
+}
+
 /**
  * Attach resolved facts to an actor, once, at the request boundary — the one place that already
  * awaited the database. Returns a new frozen actor, so the actor a predicate reads later cannot

package/src/index.ts

@@ -36,6 +36,7 @@ export {
   actorOrigin,
   agentActor,
   anonymousActor,
+  grantCovers,
   hasRole,
   hasScope,
   isActorKind,
@@ -675,6 +676,15 @@ export {
 } from './page-meta';
 /** The structural Postgres seam http, auth, action and jobs share without a `@ultimat3/db` edge. */
 export type { PgExecutor } from './pg-executor';
+/** Test support: the one name a live suite gives the database it creates (`probe-databases`). */
+export type { ProbeDatabaseEntropy } from './probe-database';
+export { PROBE_DATABASE_NAME_MAX, probeDatabaseName } from './probe-database';
+export type { ProbeDatabaseSweepOptions } from './probe-database-sweep';
+export {
+  PROBE_DATABASE_MIN_AGE_MS,
+  probeDatabaseAlive,
+  sweepProbeDatabases,
+} from './probe-database-sweep';
 export type { ProcessMetricsOptions, ProcessReading } from './process-metrics';
 export { readProcess, resetProcessMetrics, startProcessMetrics } from './process-metrics';
 export { hasPublicCause, registerPublicCause, resetPublicCauses } from './public-cause';

package/src/pg-executor.ts

@@ -6,8 +6,8 @@
  * One method, positional parameters. **`Bun.sql` does not satisfy it** — `Bun.sql.query` is
  * `undefined`; it is a tagged template whose positional form is `unsafe`, so `{ executor: Bun.sql }`
  * would `TypeError` on the first statement. What satisfies it is a client that already speaks
- * `(text, values)`, wrapped in one line — `@ultimat3/cli`'s `pgExecutorFor(client)` over
- * `@ultimat3/db`'s `DbClient.query({ text, values })` is the framework's own — or a transaction
+ * `(text, values)` — `@ultimat3/db`'s `dbExecutor()` over `DbClient.query({ text, values })` is
+ * the framework's own, and its one builder — or a transaction
  * handle, which is a client on its own connection. It answers rows, never a command tag.
  */
 export interface PgExecutor {

package/src/probe-database-sweep.ts

@@ -0,0 +1,68 @@
+// Test support: drop the probe databases a KILLED run of the same suite left behind. A per-run name
+// (`probe-database.ts`) is never reused, so nothing else would ever drop it — the fixed name it
+// replaced was dropped by the next run. Only a database whose run is provably over goes: its pid
+// dead on this host, no backend connected, AND older than `PROBE_DATABASE_MIN_AGE_MS` — a run on
+// another host that has created its database and not yet connected reads dead and idle here.
+
+import { stringField } from './error-render';
+import type { PgExecutor } from './pg-executor';
+
+/** `<prefix>_<pid>_<seconds, base 36>_<8 hex>` — exactly what `probeDatabaseName` returns. */
+const PROBE_SHAPE = /^([a-z_][a-z0-9_]*)_(\d+)_([0-9a-z]+)_[0-9a-f]{8}$/;
+
+/** A leftover younger than this is left alone: no suite takes ten minutes to make its first query. */
+export const PROBE_DATABASE_MIN_AGE_MS = 10 * 60 * 1000;
+
+export interface ProbeDatabaseSweepOptions {
+  /** Whether a pid is a live process on this host. Defaults to `probeDatabaseAlive`. */
+  readonly isAlive?: ((pid: number) => boolean) | undefined;
+  /** The clock a leftover's age is read against. Defaults to `Date.now`. */
+  readonly now?: (() => number) | undefined;
+}
+
+/**
+ * `kill(pid, 0)` delivers nothing and answers whether the process exists: `EPERM` is a process
+ * someone else owns, which is alive. Another host's pid reads as dead here, which is why the sweep
+ * also demands that nothing is connected.
+ */
+export function probeDatabaseAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (thrown) {
+    return stringField(thrown, 'code') === 'EPERM';
+  }
+}
+
+/**
+ * Drop every database sharing `probeName`'s prefix whose run is over, never `probeName` itself.
+ * Call it beside the `create database`; it answers the names it dropped. A name not shaped like
+ * `probeDatabaseName`'s answer has no siblings to find, and nothing is sent.
+ */
+export async function sweepProbeDatabases(
+  executor: PgExecutor,
+  probeName: string,
+  options: ProbeDatabaseSweepOptions = {},
+): Promise<readonly string[]> {
+  const prefix = PROBE_SHAPE.exec(probeName)?.[1];
+  if (prefix === undefined) return [];
+  const isAlive = options.isAlive ?? probeDatabaseAlive;
+  const now = (options.now ?? Date.now)();
+  const rows = await executor.query<{ datname: string; backends: number | string }>(
+    `select d.datname, (select count(*) from pg_stat_activity a where a.datname = d.datname) as backends
+       from pg_database d where d.datname like $1`,
+    [`${prefix.replaceAll('_', '\\_')}\\_%`],
+  );
+  const swept: string[] = [];
+  for (const row of rows) {
+    const shape = PROBE_SHAPE.exec(row.datname);
+    if (row.datname === probeName || shape?.[1] !== prefix) continue;
+    if (Number(row.backends) > 0 || isAlive(Number(shape[2]))) continue;
+    const createdMs = Number.parseInt(shape[3] ?? '', 36) * 1000;
+    if (!Number.isFinite(createdMs) || now - createdMs < PROBE_DATABASE_MIN_AGE_MS) continue;
+    // The name matched `PROBE_SHAPE`, so it is `[a-z0-9_]` only — quoting it needs no escape.
+    await executor.query(`drop database if exists "${row.datname}" with (force)`, []);
+    swept.push(row.datname);
+  }
+  return swept;
+}

package/src/probe-database.ts

@@ -0,0 +1,44 @@
+// Test support: the ONE name a live or contract suite gives the database it creates and drops —
+// prefix, pid, creation second (base 36), eight random hex characters. A fixed name let two runs against one server drop each
+// other's database mid-suite (#705). Here, at tier 0, because every package with such a suite can
+// import core and `@ultimat3/testing` (tier 5) is out of reach below it. `bun run probe-databases`.
+
+/** Postgres's NAMEDATALEN - 1: a longer identifier is silently truncated, so two names could meet. */
+export const PROBE_DATABASE_NAME_MAX = 63;
+
+const RANDOM_HEX = 8;
+
+/** Where a probe name's uniqueness comes from — injectable so a test can pin the answer. */
+export interface ProbeDatabaseEntropy {
+  /** Defaults to `process.pid`: two concurrent runs are two processes. */
+  readonly pid?: number | undefined;
+  /** Defaults to a fresh `crypto.randomUUID()`: two suites in one process differ by this. */
+  readonly random?: string | undefined;
+  /** Defaults to `Date.now()`: the creation second the sweep ages a leftover by. */
+  readonly now?: number | undefined;
+}
+
+/** Lowercase `[a-z0-9_]`, starting with a letter or `_` — an identifier no statement must quote. */
+function identifierPrefix(prefix: string): string {
+  const folded = prefix.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+  if (folded === '') return 'x_probe';
+  return /^[a-z_]/.test(folded) ? folded : `x_${folded}`;
+}
+
+/**
+ * A database name unique to this call, valid unquoted, at most 63 bytes — truncation takes the
+ * prefix, never the suffix. The creation second is in the name because `pg_database` records none,
+ * and `sweepProbeDatabases` must not drop a run's database in the moment between its `create` and
+ * its first connection (`<prefix>_<pid>_<seconds, base 36>_<8 hex>`).
+ */
+export function probeDatabaseName(prefix: string, entropy: ProbeDatabaseEntropy = {}): string {
+  const pid = Math.trunc(Math.abs(entropy.pid ?? process.pid));
+  const hex = (entropy.random ?? crypto.randomUUID())
+    .toLowerCase()
+    .replace(/[^0-9a-f]/g, '')
+    .slice(0, RANDOM_HEX)
+    .padEnd(RANDOM_HEX, '0');
+  const seconds = Math.floor(Math.max(0, entropy.now ?? Date.now()) / 1000).toString(36);
+  const suffix = `_${String(pid)}_${seconds}_${hex}`;
+  return `${identifierPrefix(prefix).slice(0, PROBE_DATABASE_NAME_MAX - suffix.length)}${suffix}`;
+}