akanjs 2.4.1 → 2.4.2-rc.1

package/service/predefinedAdaptor/searchIndex.ts

@@ -0,0 +1,517 @@
+import { FIELD_META } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import { type ConstantField, type ConstantModel, type FieldObject, textFieldRoles } from "akanjs/constant";
+import { type DatabaseModel, type SearchColumn, searchColumns } from "akanjs/document";
+import type { AkanSqlClient } from "./database.adaptor";
+import { descriptorHash, jsonPath, quoteIdent } from "./sqlDescriptor";
+
+export const DOC_TABLE = "search_doc";
+export const FTS_TABLE = "search_fts";
+export const DEFAULT_TOKENIZER = "unicode61 remove_diacritics 2";
+
+const SCHEMA_META_KEY = "search:schema";
+const MIRROR_META_KEY = "search:mirror";
+const DISABLED_META_KEY = "search:disabled";
+const REF_META_PREFIX = "search:ref:";
+const LOCK_META_PREFIX = "search:lock:";
+
+const LOCK_TTL_MS = 10 * 60 * 1000;
+const BACKFILL_CHUNK = 5000;
+
+const MERGE_PAGES = 64;
+const OPTIMIZE_LOCK_REF = "__optimize";
+export const OPTIMIZE_CRON_KEY = "searchIndexOptimize";
+
+export const OPTIMIZE_CRON = "17 4 * * *";
+export const RETRY_INTERVAL_KEY = "searchIndexRetry";
+
+export const RETRY_INTERVAL_MS = 60_000;
+
+export const DEFAULT_SEARCH_WEIGHTS = [10, 1, 3, 0];
+
+export interface SearchIndexOwner {
+  getConnection(): AkanSqlClient;
+  getMeta(key: string): Promise<string | undefined> | string | undefined;
+  setMeta(key: string, value: string): Promise<void>;
+}
+
+export interface SearchIndexOptions {
+  enabled: boolean;
+  tokenizer: string;
+}
+
+type SearchColumns = Record<(typeof textFieldRoles)[number], string>;
+
+/**
+ * Reads `AKAN_SEARCH_ENABLED`. Unset means enabled; an unrecognised value fails the boot rather than
+ * silently falling back, because a typo like `ture` would otherwise look identical to the default.
+ */
+export const parseSearchEnabled = (value: string | undefined) => {
+  if (value === undefined || value.trim() === "") return true;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true") return true;
+  if (normalized === "0" || normalized === "false") return false;
+  throw new Error(`Invalid AKAN_SEARCH_ENABLED value: "${value}". Use 1/true or 0/false.`);
+};
+
+/**
+ * Turns raw user input into an fts5 MATCH expression.
+ *
+ * Raw text cannot be passed through: `-`, `:`, `*`, `"` and a trailing `AND` are all fts5 syntax and each
+ * raises `SQLiteError` instead of returning no rows. Quoting every term makes the whole input literal.
+ */
+export const toMatchExpression = (
+  text: string,
+  { prefix = false, columns }: { prefix?: boolean; columns?: readonly SearchColumn[] } = {},
+) => {
+  const terms = text
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((term) => `"${term.replaceAll('"', '""')}"`);
+  if (!terms.length) return null;
+  if (prefix) terms[terms.length - 1] = `${terms[terms.length - 1]}*`;
+  const expression = terms.join(" ");
+
+  return columns?.length ? `{${columns.join(" ")}} : (${expression})` : expression;
+};
+
+/**
+ * Owns the `search_doc` mirror and its fts5 index.
+ *
+ * The mirror is maintained by SQL triggers rather than document hooks because `updateOneByQuery` and friends
+ * deliberately fire no hooks — most searchable-field mutations go through exactly that path, so an app-level
+ * hook would miss them silently.
+ */
+export class SearchIndex {
+  static readonly #docColumns = textFieldRoles.map(quoteIdent).join(", ");
+  static readonly #upsertTail = `ON CONFLICT("ref", "refId") DO UPDATE SET ${textFieldRoles
+    .map((role) => `${quoteIdent(role)} = excluded.${quoteIdent(role)}`)
+    .join(", ")}`;
+
+  static readonly #slugSeparators = [" ", "-", ".", "/", ":", "@", ",", "+", "#", "(", ")", "'"];
+
+  static #sqlString(value: string) {
+    return value.replaceAll("'", "''");
+  }
+
+  static #slug(value: string) {
+    return SearchIndex.#slugSeparators.reduce(
+      (expression, separator) => `replace(${expression}, '${SearchIndex.#sqlString(separator)}', '_')`,
+      `lower(COALESCE(${value}, ''))`,
+    );
+  }
+
+  static #filterToken(path: string, value: string) {
+    const key = SearchIndex.#sqlString(path.split(".").join("_"));
+    return `NULLIF('${key}_' || ${SearchIndex.#slug(value)}, '${key}_')`;
+  }
+
+  readonly #owner: SearchIndexOwner;
+  readonly #enabled: boolean;
+  readonly #tokenizer: string;
+  readonly #logger = new Logger("SearchIndex");
+  
+  readonly #claims = new Map<string, string>();
+
+  readonly #pending = new Map<string, [ConstantModel, DatabaseModel]>();
+
+  constructor(owner: SearchIndexOwner, { enabled, tokenizer }: SearchIndexOptions) {
+    this.#owner = owner;
+    this.#enabled = enabled;
+    this.#tokenizer = tokenizer;
+  }
+
+  get enabled() {
+    return this.#enabled;
+  }
+
+  async ensureSchema() {
+    if (!this.#enabled) {
+      
+      await this.#owner.setMeta(DISABLED_META_KEY, "1");
+      this.#logger.info("Search index disabled by AKAN_SEARCH_ENABLED; model triggers will be dropped");
+      return;
+    }
+    const conn = this.#owner.getConnection();
+    if (await this.#owner.getMeta(DISABLED_META_KEY)) {
+      await this.#clearRefHashes();
+      await conn.execute(`DELETE FROM "_akan_meta" WHERE "key" = ?`, [DISABLED_META_KEY]);
+      this.#logger.info("Search index re-enabled; every ref will be reconciled");
+    }
+    await conn.execute(
+      `CREATE TABLE IF NOT EXISTS ${quoteIdent(DOC_TABLE)} (
+        "fid" INTEGER PRIMARY KEY AUTOINCREMENT,
+        "ref" TEXT NOT NULL,
+        "refId" TEXT NOT NULL,
+        ${textFieldRoles.map((role) => `${quoteIdent(role)} TEXT NOT NULL DEFAULT ''`).join(",\n        ")},
+        UNIQUE("ref", "refId")
+      )`,
+    );
+    const hash = await descriptorHash({ doc: textFieldRoles, columns: searchColumns, tokenizer: this.#tokenizer });
+
+    if ((await this.#ftsExists()) && (await this.#owner.getMeta(SCHEMA_META_KEY)) === hash) {
+      await this.#ensureMirrorTriggers();
+      return;
+    }
+    const added = await this.#addMissingDocColumns();
+
+    await this.#dropMirrorTriggers();
+    await conn.execute(`DROP TABLE IF EXISTS ${quoteIdent(FTS_TABLE)}`);
+    try {
+      await conn.execute(
+        `CREATE VIRTUAL TABLE ${quoteIdent(FTS_TABLE)} USING fts5(
+          ${searchColumns.map(quoteIdent).join(", ")},
+          content='${DOC_TABLE}', content_rowid='fid', tokenize='${SearchIndex.#sqlString(this.#tokenizer)}')`,
+      );
+    } catch (error) {
+
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Failed to create the search index with tokenizer "${this.#tokenizer}": ${message}. Fix AKAN_SEARCH_TOKENIZER, or set AKAN_SEARCH_ENABLED=0 to run without text search.`,
+      );
+    }
+    await this.#ensureMirrorTriggers({ resync: false });
+    if (added.length) {
+      await this.#clearRefHashes();
+      this.#logger.info(`Search mirror gained ${added.join(", ")}; every ref will be reconciled`);
+    }
+    await conn.execute(`INSERT INTO ${quoteIdent(FTS_TABLE)}(${quoteIdent(FTS_TABLE)}) VALUES('rebuild')`);
+    await this.#owner.setMeta(SCHEMA_META_KEY, hash);
+  }
+
+  /** Returns whether this ref's mirror is now current. `false` means another process is rebuilding it. */
+  async ensureRef(constant: ConstantModel, database: DatabaseModel) {
+    const ref = database.refName;
+    const columns = this.#enabled ? this.#buildColumns(constant, database, "NEW") : null;
+    if (!columns) {
+      await this.#dropModelTriggers(ref);
+      return true;
+    }
+    const triggers = this.#modelTriggers(ref, columns, this.#buildColumns(constant, database, "OLD"));
+
+    const hash = await descriptorHash(triggers);
+    if ((await this.#owner.getMeta(`${REF_META_PREFIX}${ref}`)) === hash) {
+
+      await this.#createTriggers(triggers);
+      this.#pending.delete(ref);
+      return true;
+    }
+    if (!(await this.#claimLock(ref))) {
+
+      this.#pending.set(ref, [constant, database]);
+      this.#logger.warn(`Search index for ${ref} is held by another process; will retry`);
+      return false;
+    }
+    try {
+
+      await this.#dropModelTriggers(ref);
+      await this.#createTriggers(triggers);
+      const reconciled = await this.reconcileRef(ref, columns, () => this.#renewLock(ref));
+
+      if (reconciled) await this.#owner.setMeta(`${REF_META_PREFIX}${ref}`, hash);
+      if (reconciled) this.#pending.delete(ref);
+      else this.#pending.set(ref, [constant, database]);
+      return reconciled;
+    } finally {
+      await this.#releaseLock(ref);
+    }
+  }
+
+  /** Re-runs the refs another process was holding. Returns how many are still outstanding. */
+  async retryPending() {
+    for (const [ref, [constant, database]] of [...this.#pending]) {
+      if (await this.ensureRef(constant, database)) this.#logger.info(`Search index for ${ref} is current again`);
+    }
+    return this.#pending.size;
+  }
+
+  /**
+   * Rebuilds one ref's mirror rows in id-ordered chunks so a large table does not block the boot. `onChunk` runs
+   * between chunks and reports whether this process still holds the claim: a backfill that outlives the lock TTL
+   * would otherwise keep writing rows underneath the `DELETE` of the process that took over. Returns whether the
+   * whole table was covered.
+   */
+  async reconcileRef(ref: string, columns: SearchColumns, onChunk?: () => Promise<boolean>) {
+    const conn = this.#owner.getConnection();
+    await conn.execute(`DELETE FROM ${quoteIdent(DOC_TABLE)} WHERE "ref" = ?`, [ref]);
+    let cursor = "";
+    for (;;) {
+      const rows = await conn
+        .prepare(
+          `SELECT "id" FROM ${quoteIdent(ref)} WHERE "removedAt" IS NULL AND "id" > ? ORDER BY "id" LIMIT ${BACKFILL_CHUNK}`,
+        )
+        .all<{ id: string }>(cursor);
+      const last = rows.at(-1)?.id;
+      if (!last) return true;
+      await conn.execute(
+        `INSERT INTO ${quoteIdent(DOC_TABLE)}("ref", "refId", ${SearchIndex.#docColumns})
+         SELECT '${ref}', NEW."id", ${this.#columnList(columns)}
+         FROM ${quoteIdent(ref)} AS NEW
+         WHERE NEW."removedAt" IS NULL AND NEW."id" > ? AND NEW."id" <= ?
+         ${SearchIndex.#upsertTail}`,
+        [cursor, last],
+      );
+      if (rows.length < BACKFILL_CHUNK) return true;
+      cursor = last;
+      if (onChunk && !(await onChunk())) {
+        this.#logger.warn(`Search backfill for ${ref} stopped: another process took the claim over`);
+        return false;
+      }
+    }
+  }
+
+  /** Merges accumulated fts5 segments. Returns whether this process was the one that did the work. */
+  async optimize() {
+    if (!this.#enabled) return false;
+    
+    if (!(await this.#claimLock(OPTIMIZE_LOCK_REF))) return false;
+    try {
+      await this.#owner
+        .getConnection()
+        .execute(`INSERT INTO ${quoteIdent(FTS_TABLE)}(${quoteIdent(FTS_TABLE)}, rank) VALUES('merge', ?)`, [
+          MERGE_PAGES,
+        ]);
+      return true;
+    } catch (error) {
+      
+      this.#logger.warn(`Search index merge failed: ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    } finally {
+      await this.#releaseLock(OPTIMIZE_LOCK_REF);
+    }
+  }
+
+  /**
+   * Drops a ref's triggers so a bulk import skips the per-row mirror write. Pair with `resume`.
+   *
+   * The hash is cleared here rather than in `resume` alone: a process that dies mid-import never reaches `resume`,
+   * and a boot that finds the hash intact recreates the triggers and skips the backfill, leaving everything
+   * written in between missing from the mirror for good.
+   */
+  async suspend(database: DatabaseModel) {
+    await this.#owner.setMeta(`${REF_META_PREFIX}${database.refName}`, "");
+    await this.#dropModelTriggers(database.refName);
+  }
+
+  /** Returns whether the mirror is current again; `false` means another process holds the rebuild. */
+  async resume(constant: ConstantModel, database: DatabaseModel) {
+    await this.#owner.setMeta(`${REF_META_PREFIX}${database.refName}`, "");
+    return await this.ensureRef(constant, database);
+  }
+
+  #columnList(columns: SearchColumns) {
+    return textFieldRoles.map((role) => columns[role]).join(", ");
+  }
+
+  async #clearRefHashes() {
+    await this.#owner.getConnection().execute(`DELETE FROM "_akan_meta" WHERE "key" LIKE '${REF_META_PREFIX}%'`);
+  }
+
+  /**
+   * Widens an existing mirror to a column this build knows about but the database predates. Without it a release
+   * that adds a role fails every boot on `rebuild`, which is the migration step the descriptor hash exists to
+   * avoid. A column dropped from a later build is left in place; it defaults to empty and costs nothing.
+   */
+  async #addMissingDocColumns() {
+    const conn = this.#owner.getConnection();
+    const existing = new Set(
+      (await conn.prepare(`PRAGMA table_info(${quoteIdent(DOC_TABLE)})`).all<{ name: string }>()).map(
+        (column) => column.name,
+      ),
+    );
+    const missing = textFieldRoles.filter((role) => !existing.has(role));
+    for (const role of missing) {
+      await conn.execute(
+        `ALTER TABLE ${quoteIdent(DOC_TABLE)} ADD COLUMN ${quoteIdent(role)} TEXT NOT NULL DEFAULT ''`,
+      );
+    }
+    return missing;
+  }
+
+  #mirrorTriggers(): [string, string][] {
+    const cols = searchColumns.map(quoteIdent).join(", ");
+    const fts = quoteIdent(FTS_TABLE);
+    const doc = quoteIdent(DOC_TABLE);
+    const values = (alias: "new" | "old") => searchColumns.map((col) => `${alias}.${quoteIdent(col)}`).join(", ");
+    const remove = `INSERT INTO ${fts}(${fts}, rowid, ${cols}) VALUES('delete', old."fid", ${values("old")})`;
+    const insert = `INSERT INTO ${fts}(rowid, ${cols}) VALUES(new."fid", ${values("new")})`;
+    return [
+      [`${DOC_TABLE}_ai`, `AFTER INSERT ON ${doc} BEGIN ${insert}; END`],
+      [`${DOC_TABLE}_ad`, `AFTER DELETE ON ${doc} BEGIN ${remove}; END`],
+      [`${DOC_TABLE}_au`, `AFTER UPDATE ON ${doc} BEGIN ${remove}; ${insert}; END`],
+    ];
+  }
+
+  /**
+   * Only replaces these when their definition actually changed. A mirror row written while `search_doc_au` is
+   * missing leaves fts5 holding the previous text: the current value stops matching, the old one returns a ghost
+   * hit, and `integrity-check` still passes — so the damage is both silent and invisible to the usual check.
+   * The replacing path resyncs the index afterwards, unless the caller is about to rebuild it anyway.
+   */
+  async #ensureMirrorTriggers({ resync = true } = {}) {
+    const conn = this.#owner.getConnection();
+    const triggers = this.#mirrorTriggers();
+    const hash = await descriptorHash(triggers);
+    if ((await this.#owner.getMeta(MIRROR_META_KEY)) === hash) {
+      await this.#createTriggers(triggers);
+      return;
+    }
+    await this.#dropMirrorTriggers();
+    await this.#createTriggers(triggers);
+    if (resync) await conn.execute(`INSERT INTO ${quoteIdent(FTS_TABLE)}(${quoteIdent(FTS_TABLE)}) VALUES('rebuild')`);
+    await this.#owner.setMeta(MIRROR_META_KEY, hash);
+  }
+
+  async #dropMirrorTriggers() {
+    const conn = this.#owner.getConnection();
+    for (const [name] of this.#mirrorTriggers()) await conn.execute(`DROP TRIGGER IF EXISTS ${quoteIdent(name)}`);
+  }
+
+  async #ftsExists() {
+    const table = await this.#owner
+      .getConnection()
+      .prepare(`SELECT "name" FROM "sqlite_master" WHERE "type" = 'table' AND "name" = ?`)
+      .get<{ name: string }>(FTS_TABLE);
+    return !!table;
+  }
+
+  async #createTriggers(triggers: [string, string][]) {
+    const conn = this.#owner.getConnection();
+    for (const [name, sql] of triggers) {
+
+      await conn.execute(`CREATE TRIGGER IF NOT EXISTS ${quoteIdent(name)} ${sql}`);
+    }
+  }
+
+  async #dropModelTriggers(ref: string) {
+    const conn = this.#owner.getConnection();
+    for (const suffix of ["ai", "au", "soft", "ad"]) {
+      await conn.execute(`DROP TRIGGER IF EXISTS ${quoteIdent(`${ref}_search_${suffix}`)}`);
+    }
+  }
+
+  #modelTriggers(ref: string, next: SearchColumns, prev: SearchColumns | null): [string, string][] {
+    const table = quoteIdent(ref);
+    const doc = quoteIdent(DOC_TABLE);
+    const upsert = `INSERT INTO ${doc}("ref", "refId", ${SearchIndex.#docColumns})
+      VALUES ('${ref}', NEW."id", ${this.#columnList(next)}) ${SearchIndex.#upsertTail}`;
+    const purge = `DELETE FROM ${doc} WHERE "ref" = '${ref}' AND "refId" = %ID%`;
+
+    const changed = prev ? textFieldRoles.map((role) => `${next[role]} IS NOT ${prev[role]}`).join(" OR ") : "1 = 1";
+    const triggers: [string, string][] = [
+      [`${ref}_search_ai`, `AFTER INSERT ON ${table} WHEN NEW."removedAt" IS NULL BEGIN ${upsert}; END`],
+      [
+        `${ref}_search_au`,
+        `AFTER UPDATE ON ${table} WHEN NEW."removedAt" IS NULL AND (OLD."removedAt" IS NOT NULL OR (${changed}))
+         BEGIN ${upsert}; END`,
+      ],
+      [
+        `${ref}_search_soft`,
+        `AFTER UPDATE ON ${table} WHEN NEW."removedAt" IS NOT NULL AND OLD."removedAt" IS NULL
+         BEGIN ${purge.replace("%ID%", 'NEW."id"')}; END`,
+      ],
+      [`${ref}_search_ad`, `AFTER DELETE ON ${table} BEGIN ${purge.replace("%ID%", 'OLD."id"')}; END`],
+    ];
+    return triggers;
+  }
+
+  /**
+   * One conditional upsert rather than read-then-write inside `transaction()`: that helper detects nesting through
+   * AsyncLocalStorage, so a claim raised from an unrelated async context opens a second `BEGIN IMMEDIATE` on the
+   * same connection and one of the two dies. A single statement is atomic in SQLite, which is all a claim needs.
+   */
+  async #claimLock(ref: string) {
+    const now = Date.now();
+    const token = String(now);
+    const claimed = await this.#owner
+      .getConnection()
+      .prepare(
+        `INSERT INTO "_akan_meta" ("key", "value", "updatedAt") VALUES (?, ?, ?)
+         ON CONFLICT("key") DO UPDATE SET "value" = ?, "updatedAt" = ?
+         WHERE CAST("_akan_meta"."value" AS INTEGER) < ?
+         RETURNING "value"`,
+      )
+      .get<{ value: string }>(`${LOCK_META_PREFIX}${ref}`, token, now, token, now, now - LOCK_TTL_MS);
+    if (!claimed) return false;
+    this.#claims.set(ref, token);
+    return true;
+  }
+
+  /**
+   * Extends this process's claim, and reports `false` once someone else holds it. Renew and release both match on
+   * the stored token: an unconditional write would let a process that stalled past the TTL take the claim back
+   * from whoever legitimately replaced it, and then both would reconcile the same ref over each other.
+   */
+  async #renewLock(ref: string) {
+    const held = this.#claims.get(ref);
+    if (!held) return false;
+    const now = Date.now();
+    const token = String(now);
+    const renewed = await this.#owner
+      .getConnection()
+      .prepare(`UPDATE "_akan_meta" SET "value" = ?, "updatedAt" = ? WHERE "key" = ? AND "value" = ? RETURNING "value"`)
+      .get<{ value: string }>(token, now, `${LOCK_META_PREFIX}${ref}`, held);
+    if (!renewed) {
+      this.#claims.delete(ref);
+      return false;
+    }
+    this.#claims.set(ref, token);
+    return true;
+  }
+
+  async #releaseLock(ref: string) {
+    const held = this.#claims.get(ref);
+    if (!held) return;
+    this.#claims.delete(ref);
+    await this.#owner
+      .getConnection()
+      .execute(`DELETE FROM "_akan_meta" WHERE "key" = ? AND "value" = ?`, [`${LOCK_META_PREFIX}${ref}`, held]);
+  }
+
+  #buildColumns(constant: ConstantModel, database: DatabaseModel, alias: "NEW" | "OLD"): SearchColumns | null {
+    const paths = constant.full.text;
+    const fields = database.doc[FIELD_META] as unknown as FieldObject;
+    if (!paths || !fields) return null;
+    const columns = {} as SearchColumns;
+    let declared = false;
+    for (const role of textFieldRoles) {
+      const rolePaths = [...paths[role], ...paths.children[role]];
+      const parts = rolePaths
+        .map((path) => this.#roleExpression(fields, path, role, alias))
+        .filter((part): part is string => !!part);
+      if (parts.length) declared = true;
+      columns[role] = parts.length ? `TRIM(${parts.join(` || ' ' || `)})` : `''`;
+    }
+    return declared ? columns : null;
+  }
+
+  #roleExpression(fields: FieldObject, path: string, role: string, alias: "NEW" | "OLD") {
+    const doc = `${alias}.${quoteIdent("_doc")}`;
+    const segments = path.split(".");
+    let current: FieldObject | undefined = fields;
+    let arrayAt = -1;
+    for (const [idx, segment] of segments.entries()) {
+      const field: ConstantField | undefined = current?.[segment];
+      if (!field) return null;
+      if (field.arrDepth > 0 && arrayAt < 0) arrayAt = idx;
+      current = field.modelRef[FIELD_META] as unknown as FieldObject | undefined;
+    }
+
+    const wrap = (value: string) => (role === "filter" ? SearchIndex.#filterToken(path, value) : value);
+    const rows = (column: string, from: string, where = "") =>
+      `COALESCE((SELECT group_concat(${wrap(column)}, ' ') FROM ${from}${where}), '')`;
+    if (arrayAt < 0)
+      return `COALESCE(${wrap(`json_extract(${doc}, '${SearchIndex.#sqlString(jsonPath(path))}')`)}, '')`;
+    const array = `'${SearchIndex.#sqlString(jsonPath(segments.slice(0, arrayAt + 1).join(".")))}'`;
+    if (arrayAt === segments.length - 1) return rows("value", `json_each(${doc}, ${array})`);
+    const leaf = SearchIndex.#sqlString(segments[segments.length - 1]);
+    const tree = `json_tree(${doc}, ${array})`;
+
+    return rows(
+      `t."atom"`,
+      `${tree} AS t`,
+      ` WHERE t."atom" IS NOT NULL AND (t."key" = '${leaf}'
+         OR t."parent" IN (SELECT p."id" FROM ${tree} AS p WHERE p."key" = '${leaf}'))`,
+    );
+  }
+}

package/service/predefinedAdaptor/sqlDescriptor.ts

@@ -0,0 +1,25 @@
+export const quoteIdent = (identifier: string) => `"${identifier.replaceAll('"', '""')}"`;
+
+export const jsonPath = (path: string) =>
+  `$.${path
+    .split(".")
+    .map((part) => part.replaceAll('"', '\\"'))
+    .join(".")}`;
+
+export const stableJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, val]) => `${JSON.stringify(key)}:${stableJson(val)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+};
+
+/** Stable hash of a schema descriptor, stored in `_akan_meta` so a changed definition is detected without migrations. */
+export const descriptorHash = async (value: unknown) => {
+  const bytes = new TextEncoder().encode(stableJson(value));
+  const hash = await crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(hash)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};

package/signal/signalContext.ts

@@ -125,6 +125,38 @@ export class SignalContext<
       }),
     );
   }
+  /**
+   * Re-checks this context's guards outside of a request, for a websocket room that is already
+   * subscribed. Only global middlewares run: they carry the account resolution this depends on,
+   * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
+   */
+  async authorize(): Promise<boolean> {
+    try {
+      await this.#withMiddleware(async () => await this.#checkGuards(), { endpointMiddlewares: false })();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  #withMiddleware(
+    coreExec: () => Promise<unknown>,
+    { endpointMiddlewares = true }: { endpointMiddlewares?: boolean } = {},
+  ): () => Promise<unknown> {
+    const middlewares = [
+      ...this.#middleware.values(),
+      ...(endpointMiddlewares ? (this.endpointInfo.signalOption.middlewares ?? []) : []),
+    ];
+    if (middlewares.length === 0) return coreExec;
+    let next = coreExec;
+    for (let i = middlewares.length - 1; i >= 0; i--) {
+      const MiddlewareCls = middlewares[i];
+      if (!MiddlewareCls) continue;
+      const middleware = new MiddlewareCls();
+      const currentNext = next;
+      next = async () => await (await middleware.use(this.getEnv()))(this, currentNext);
+    }
+    return next;
+  }
   async exec() {
     if (!this.trace) return await this.#exec();
     return await runWithTrace(this.trace, async () => {
@@ -137,7 +169,6 @@ export class SignalContext<
   }
   async #exec() {
     if (!this.endpointInfo.execFn) throw new Exception.Error("Exec function is not set");
-    const endpointMiddlewares = this.endpointInfo.signalOption.middlewares ?? [];
     const coreExec = async () => {
       if (!this.endpointInfo.execFn) throw new Exception.Error("Exec function is not set");
       if (this.trace) await traceSpan("guards", () => this.#checkGuards());
@@ -158,17 +189,7 @@ export class SignalContext<
         async () => await this.endpointInfo.execFn?.call(this.adaptor, ...this.args, ...this.internalArgs),
       );
     };
-    let next = coreExec;
-    if (this.#middleware.size > 0 || endpointMiddlewares.length > 0) {
-      const middlewares = [...this.#middleware.values(), ...endpointMiddlewares];
-      for (let i = middlewares.length - 1; i >= 0; i--) {
-        const MiddlewareCls = middlewares[i];
-        if (!MiddlewareCls) continue;
-        const middleware = new MiddlewareCls();
-        const currentNext = next;
-        next = async () => await (await middleware.use(this.getEnv()))(this, currentNext);
-      }
-    }
+    const next = this.#withMiddleware(coreExec);
     const result = this.trace ? await traceSpan("execChain", () => next()) : await next();
     if (this.endpointInfo.type === "pubsub") return;
     if (result instanceof Response) return result;
@@ -340,6 +361,10 @@ export class SignalContext<
     if (this.transport !== "websocket") throw new Error("Transport is not websocket");
     return this.ctx as WebSocketExecutionContext<Appended>;
   }
+  get<T = unknown>(key: string): T | null {
+    if (this.transport === "http") return this.getHttpContext<{ [key: string]: T }>().req[key] ?? null;
+    return this.getWebSocketContext<{ [key: string]: T }>().ws.data[key] ?? null;
+  }
   getRoomId(key: string) {
     if (this.transport !== "websocket") throw new Error("Transport is not websocket");
     else if (this.endpointInfo.type !== "pubsub") throw new Error("Endpoint is not pubsub");

package/signal/types.ts

@@ -140,4 +140,5 @@ export type WebsocketReqData = { key: string; data: unknown[]; subscribe?: boole
 export type WebsocketMessageData = { type: "msg"; key: string; data: object | object[] };
 export type WebsocketSubscribeAck = { type: "sub"; roomId: string; subscribe: boolean };
 export type WebsocketPublishData = { type: "pub"; roomId: string; data: object | object[] };
-export type WebsocketResData = WebsocketMessageData | WebsocketSubscribeAck | WebsocketPublishData;
+export type WebsocketAuthAck = { type: "auth"; revokedRooms: string[] };
+export type WebsocketResData = WebsocketMessageData | WebsocketSubscribeAck | WebsocketPublishData | WebsocketAuthAck;

package/types/client/csrTypes.d.ts

@@ -43,6 +43,13 @@ export interface PageConfig {
     rscPatchHeadSafe?: boolean;
     topSafeAreaColor?: string;
     bottomSafeAreaColor?: string;
+    /**
+     * Keeps the route out of `akan build`. The route still serves under `akan start`, but nothing about it
+     * reaches production: no bundle, no manifest entry, no URL. On a `_layout`, every route under that
+     * directory is excluded with it. Must be written as a literal `true`/`false` — the build reads it from
+     * the source without evaluating the module.
+     */
+    devOnly?: boolean;
 }
 export interface CsrState {
     transition: TransitionType;

package/types/client/rscNavigation.d.ts

@@ -1,17 +1,25 @@
 declare global {
     var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
+    var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
     var __AKAN_RSC_NAVIGATE__: ((href: string, options?: {
         replace?: boolean;
         scrollToTop?: boolean;
     }) => Promise<void>) | undefined;
 }
 export declare const clearRscNavigationCache: () => void;
+/**
+ * True when the page tree currently on screen was replayed from the RSC navigation cache instead of
+ * fetched from the server. Data hydrated out of such a payload can be arbitrarily old, so anything
+ * that must show current values should refetch.
+ */
+export declare const isRscNavigationFromCache: () => boolean;
 export declare const navigateRsc: (href: string, options?: {
     replace?: boolean;
     scrollToTop?: boolean;
 }) => Promise<void> | undefined;
 export declare const useRscNavigation: () => {
     clearCache: () => void;
+    isFromCache: () => boolean;
     navigate: (href: string, options?: {
         replace?: boolean;
         scrollToTop?: boolean;

package/types/common/index.d.ts

@@ -27,3 +27,4 @@ export { sleep } from "./sleep.d.ts";
 export { splitVersion } from "./splitVersion.d.ts";
 export { getBasePathFromPathname, parseBasePaths } from "./subRoute.d.ts";
 export type * from "./types.d.ts";
+export { type WebsocketAuthAckData, type WebsocketAuthRequest, websocketAuthContract, } from "./websocketAuth.d.ts";