heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/occupied-keys.mjs

@@ -0,0 +1,141 @@
+/**
+ * occupied-keys.mjs — tier-aware vault KEY occupancy for the id minters
+ * ([[HS-FJWL]]).
+ *
+ * `collectOccupiedKeysEitherKind` (spec-id-lib.mjs) is a `readdirSync` walk of
+ * `specs/**` basenames. That is complete on the DISK tier and blind on the
+ * CLOUD tier: since the cutover to cloud reliance a filed spec gets a Neon row
+ * and NO local `.md` (`landed.onDisk: false`), so the walk answers from a local
+ * clone that is not empty, just STALE — a large, plausible-looking set that
+ * silently omits every cloud-only spec. A blind scan is tolerable for FAMILY
+ * keys (they are a "pick something fresh" default, not a uniqueness gate —
+ * spec-id-lib.mjs `collectOccupiedFamilyKeysFromVault`) and unsound for FILE
+ * keys, which under Naming V3 ARE the unique per-file identity that `id:` keys
+ * onto. Re-issuing one mints a duplicate id.
+ *
+ * Shape follows the existing `*ViaTier` family and composes on
+ * {@link readViaSelector} — {@link collectOccupiedCaptureIdsViaTier}
+ * (capture-tools.mjs) is the direct precedent.
+ *
+ * CONSOLE READ STRATEGY — full enumeration, not a per-candidate existence
+ * probe. `GET /api/specs/resolve?q=<key>` would be one request per mint, but it
+ * answers `404 { error: "not_found" }` BOTH for "this key is free" and for "you
+ * are not authorized for this vault" (`resolveCallerVaultScope` →
+ * `not_found`, spex-console/src/app/api/specs/resolve/route.ts), so a
+ * signed-out session would read every key as free and mint duplicates — the
+ * exact failure this module exists to prevent. It also cannot see family keys
+ * in era-1 (`HS-TASK-<family>-…`) or era-3 (`HS-<fileKey>-<family>-TYPE-…`)
+ * positions, because its prefix tier only matches a LEADING `<token>-`.
+ * Enumerating `GET /api/specs?fields=id,basename` instead applies the SAME
+ * basename parsers the disk walk uses, so both namespaces and all three eras
+ * are covered identically, and an unauthorized answer is detectable (it comes
+ * back as an empty page — see the empty-set refusal below).
+ */
+
+import { consoleFetch as defaultConsoleFetch } from './console-transport.mjs';
+import { walkSpecListPages } from './list-tools.mjs';
+import { readViaSelector } from './read-path.mjs';
+import {
+  bareFileKeyOf,
+  collectOccupiedKeysEitherKind,
+  fileKeyFromBasename,
+  parseSpecId,
+} from './spec-id-lib.mjs';
+
+/** The projection the cloud occupancy walk asks for — two fields, ~60 bytes/row. */
+export const OCCUPIED_KEYS_LIST_PATH = '/api/specs?fields=id,basename';
+
+/** `routeLabel` for the selector's unreachable-console error. */
+const ROUTE_LABEL = `GET ${OCCUPIED_KEYS_LIST_PATH}`;
+
+/**
+ * Cross-namespace occupancy (FILE keys ∪ FAMILY keys) from `GET /api/specs`
+ * rows — the cloud twin of {@link collectOccupiedKeysEitherKind}'s union.
+ *
+ * Reads the same two atoms the disk walk reads, from the same parsers:
+ *   - `basename` → `fileKeyFromBasename` (era-3 leading token / era-1-2
+ *     after-TYPE token) and `parseSpecId(...).familyKey` (positional in every
+ *     era).
+ *   - `id` → a bare era-3 `HS-<fileKey>` (`bareFileKeyOf`), plus the positional
+ *     atoms of a full id. The disk walk has only filenames to go on; list rows
+ *     carry the stored `id:` too, so this is a strict superset — never a
+ *     smaller set than the disk scan would return for the same specs.
+ *
+ * @param {Array<{ id?: string|null, basename?: string|null }>} rows
+ * @returns {Set<string>} uppercase keys
+ */
+export function occupiedKeysFromSpecRows(rows) {
+  const occupied = new Set();
+  const addFrom = (value) => {
+    if (typeof value !== 'string' || !value.trim()) return;
+    const bare = bareFileKeyOf(value);
+    if (bare) occupied.add(bare);
+    const fileKey = fileKeyFromBasename(value);
+    if (fileKey) occupied.add(fileKey.toUpperCase());
+    const parsed = parseSpecId(value);
+    if (parsed?.familyKey) occupied.add(parsed.familyKey.toUpperCase());
+    if (parsed?.fileKey) occupied.add(parsed.fileKey.toUpperCase());
+  };
+  for (const row of Array.isArray(rows) ? rows : []) {
+    addFrom(row?.basename);
+    addFrom(row?.id);
+  }
+  return occupied;
+}
+
+/**
+ * Tier-aware {@link collectOccupiedKeysEitherKind}.
+ *
+ * - `disk`: byte-identical to today's scan; `neonRead` never runs, so a
+ *   disk-tier mint makes ZERO console calls.
+ * - `neon`: walks `GET /api/specs?fields=id,basename` to exhaustion. The route
+ *   caps a page at 500 rows and hands back `next_cursor`
+ *   ([[HS-0R2X-8KK5-EPIC]]); {@link walkSpecListPages} follows it, because a
+ *   caller that reads page 1 only would UNDER-COUNT occupancy, which is the
+ *   same duplicate-id bug wearing a different hat.
+ *
+ * FAILS LOUDLY, deliberately, and in TWO ways the read path does not:
+ *
+ *  1. An unreachable/erroring console throws
+ *     {@link ConsoleUnreachableCloudModeError} via the selector — no silent
+ *     disk fallback. That is the selector's own contract, and it is the right
+ *     one here for a stronger reason than it is for a read: handing out a
+ *     possibly-duplicate id is worse than refusing to mint. A read that falls
+ *     back to a stale local copy shows stale data; a MINT that falls back to a
+ *     stale local copy writes a colliding id into the vault of record.
+ *  2. An EMPTY occupancy set from the cloud is refused rather than returned.
+ *     `GET /api/specs` answers `200 { specs: [], vaultScope: { authorized:
+ *     false } }` when the caller is not authorized for the vault
+ *     (spex-console/src/app/api/specs/route.ts), and an empty set is exactly
+ *     what makes every candidate key look free. A real vault that could be
+ *     minted into is never empty — the spec being minted is filed INTO an
+ *     existing vault — so "zero rows" is always either a signed-out session or
+ *     a wrong-vault scope, never a legitimate answer.
+ *
+ * @param {string} vaultRoot
+ * @param {{ tier: 'disk'|'neon', consoleUrl?: string, consoleFetch?: Function, walk?: Function }} opts
+ * @returns {Promise<Set<string>>}
+ */
+export async function collectOccupiedKeysEitherKindViaTier(
+  vaultRoot,
+  { tier, consoleUrl, consoleFetch = defaultConsoleFetch, walk = walkSpecListPages } = {},
+) {
+  return readViaSelector({
+    tier,
+    diskRead: () => collectOccupiedKeysEitherKind(vaultRoot),
+    neonRead: async () => {
+      const rows = await walk(consoleFetch, OCCUPIED_KEYS_LIST_PATH);
+      if (!Array.isArray(rows) || rows.length === 0) {
+        throw new Error(
+          `${ROUTE_LABEL} returned 0 specs — refusing to mint against an empty occupancy set. ` +
+            `An unauthorized or wrong-vault caller gets \`200 { specs: [], vaultScope: ` +
+            `{ authorized: false } }\` from this route, which is indistinguishable from ` +
+            `"every key is free"; minting on it would hand out a duplicate file key.`,
+        );
+      }
+      return occupiedKeysFromSpecRows(rows);
+    },
+    routeLabel: ROUTE_LABEL,
+    consoleUrl,
+  });
+}