@ultimat3/manifest 20.2.1 → 22.0.0

package/README.md

@@ -150,3 +150,15 @@ never writes, and it never synthesises a sentence.
 | `X_MANIFEST_BREAKING` | contract broke with no major bump | bump the version, or restore |
 | `X_AGENTS_MD_MISSING` | no `AGENTS.md` | write one by hand |
 | `X_AGENTS_MD_TOO_LARGE` | over the byte budget | move facts to `x.manifest.json` |
+
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `AgentsMdMissingError` | `X_AGENTS_MD_MISSING` | `src/errors.ts` |
+| `AgentsMdTooLargeError` | `X_AGENTS_MD_TOO_LARGE` | `src/errors.ts` |
+| `ManifestBreakingError` | `X_MANIFEST_BREAKING` | `src/errors.ts` |
+| `ManifestDriftError` | `X_MANIFEST_DRIFT` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/manifest",
-  "version": "20.2.1",
+  "version": "22.0.0",
   "description": "x.manifest.json: deterministic generated facts, contract diff, AGENTS.md budget",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "20.2.1",
-    "@ultimat3/core": "20.2.1",
-    "@ultimat3/entity": "20.2.1",
-    "@ultimat3/jobs": "20.2.1",
-    "@ultimat3/query": "20.2.1"
+    "@ultimat3/action": "22.0.0",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/entity": "22.0.0",
+    "@ultimat3/jobs": "22.0.0",
+    "@ultimat3/query": "22.0.0",
+    "@ultimat3/realtime": "22.0.0"
   }
 }

package/src/agents-md.ts

@@ -81,13 +81,31 @@ export async function assertAgentsMd(input: CheckAgentsMdInput = {}): Promise<Ag
   return check;
 }
 
+/** A header naming a column of generated facts. A conventions table (`| Rule | Detail |`) names none. */
+const FACT_COLUMN = /\b(column|entity|entities|route|routes|endpoint|endpoints|table|type)\b/i;
+
+/** A table separator row: `| --- | :-: |`, pipes, dashes, colons and spaces only. */
+const SEPARATOR = /^\s*\|[\s|:-]+\|\s*$/;
+
+/**
+ * The HEADER row of every markdown table — the line directly above a separator. The columns are
+ * what a table tabulates; a word in a cell is prose about a convention, which is what the file is
+ * for, and warning on it flagged the scaffold's own conventions table on every app (slice 11 i).
+ */
+const tableHeaders = (text: string): readonly string[] => {
+  const lines = text.split('\n');
+  return lines.filter(
+    (line, index) => line.trim().startsWith('|') && SEPARATOR.test(lines[index + 1] ?? ''),
+  );
+};
+
 /**
  * Warn when the file has started duplicating generated facts. Duplication is how a context
  * file goes stale: the copy and the source drift, and the agent believes the copy.
  */
 function warningsFor(text: string): readonly string[] {
   const warnings: string[] = [];
-  if (/^\s*\|.*\|\s*$/m.test(text) && /\b(column|entity|route|endpoint)\b/i.test(text)) {
+  if (tableHeaders(text).some((header) => FACT_COLUMN.test(header))) {
     warnings.push('looks like it tabulates schema or route facts; those live in x.manifest.json');
   }
   if (text.split('\n').length > 200) {

package/src/build.ts

@@ -19,6 +19,7 @@
 import { canonicalJson } from '@ultimat3/core';
 import type {
   ActionFact,
+  ChannelFact,
   EntityFact,
   ErrorCodeFact,
   JobFact,
@@ -36,6 +37,7 @@ export interface ManifestSources {
   readonly entities?: readonly EntityFact[];
   readonly actions?: readonly ActionFact[];
   readonly queries?: readonly QueryFact[];
+  readonly channels?: readonly ChannelFact[];
   readonly jobs?: readonly JobFact[];
   readonly tasks?: readonly TaskFact[];
   readonly policies?: readonly PolicyFact[];
@@ -48,6 +50,7 @@ export function buildManifest(sources: ManifestSources): Manifest {
   const entities = sortBy(sources.entities ?? [], (e) => e.name).map(normalizeEntity);
   const actions = sortBy(sources.actions ?? [], (a) => a.name).map(normalizeAction);
   const queries = sortBy(sources.queries ?? [], (q) => q.name).map(normalizeQuery);
+  const channels = sortBy(sources.channels ?? [], (c) => c.name).map(normalizeChannel);
   const jobs = sortBy(sources.jobs ?? [], (j) => j.name).map(normalizeJob);
   const tasks = sortBy(sources.tasks ?? [], (t) => t.name).map((t) => ({
     ...t,
@@ -70,6 +73,7 @@ export function buildManifest(sources: ManifestSources): Manifest {
     ...policies.map((p) => p.permission),
     ...actions.flatMap((a) => a.permissions),
     ...queries.flatMap((q) => q.permissions),
+    ...channels.flatMap((c) => c.permissions),
   ]);
 
   const body = {
@@ -79,6 +83,7 @@ export function buildManifest(sources: ManifestSources): Manifest {
     entities,
     actions,
     queries,
+    channels,
     jobs,
     tasks,
     policies,
@@ -152,6 +157,14 @@ const normalizeQuery = (query: QueryFact): QueryFact => ({
   ...(query.subscribes === undefined ? {} : { subscribes: [...query.subscribes].sort() }),
 });
 
+// `params` keep their DECLARED order — it is the order a topic's segments are spelled in, so it is
+// part of the wire contract, not a set.
+const normalizeChannel = (channel: ChannelFact): ChannelFact => ({
+  ...channel,
+  records: [...channel.records].sort(),
+  permissions: [...channel.permissions].sort(),
+});
+
 // Job steps keep their DECLARED order — a job's steps are a sequence, not a set, and
 // sorting them would misrepresent the program.
 const normalizeJob = (job: JobFact): JobFact => ({ ...job, steps: [...job.steps] });

package/src/diff-channels.ts

@@ -0,0 +1,74 @@
+// Realtime channels in a contract diff. A client derives a channel's topic from its NAME and
+// PARAMS, so either moving breaks every page built against the old ones; its subscribe policy is
+// judged like any operation's, on the permissions it requires.
+
+import { canonicalJson } from '@ultimat3/core';
+import type { ManifestChange } from './diff-change';
+import { index } from './diff-change';
+import { diffPermissions } from './diff-operations';
+import type { ChannelFact } from './schema';
+
+export function diffChannels(
+  before: readonly ChannelFact[],
+  after: readonly ChannelFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByName = index(after, (c) => c.name);
+  const beforeByName = index(before, (c) => c.name);
+
+  for (const channel of before) {
+    const next = afterByName.get(channel.name);
+    const path = `channels.${channel.name}`;
+    if (next === undefined) {
+      changes.push({ kind: 'breaking', path, detail: 'channel removed' });
+      continue;
+    }
+    if (canonicalJson(channel.params) !== canonicalJson(next.params)) {
+      changes.push({ kind: 'breaking', path: `${path}.params`, detail: 'params changed' });
+    }
+    if (channel.policy !== next.policy) {
+      changes.push({
+        kind: 'breaking',
+        path: `${path}.policy`,
+        detail: `policy ${channel.policy} -> ${next.policy}`,
+      });
+    }
+    changes.push(...diffPermissions(path, channel, next));
+    // Losing a record type or the events stream breaks a page that renders them; gaining one
+    // breaks nobody.
+    for (const type of channel.records) {
+      if (!next.records.includes(type)) {
+        changes.push({
+          kind: 'breaking',
+          path: `${path}.records.${type}`,
+          detail: 'no longer carried',
+        });
+      }
+    }
+    for (const type of next.records) {
+      if (!channel.records.includes(type)) {
+        changes.push({ kind: 'additive', path: `${path}.records.${type}`, detail: 'now carried' });
+      }
+    }
+    if (channel.events !== next.events) {
+      changes.push({
+        kind: next.events ? 'additive' : 'breaking',
+        path: `${path}.events`,
+        detail: `events ${String(channel.events)} -> ${String(next.events)}`,
+      });
+    }
+    if (channel.catchUp !== next.catchUp) {
+      changes.push({
+        kind: 'internal',
+        path: `${path}.catchUp`,
+        detail: `catch-up read ${channel.catchUp} -> ${next.catchUp}`,
+      });
+    }
+  }
+  for (const channel of after) {
+    if (!beforeByName.has(channel.name)) {
+      changes.push({ kind: 'additive', path: `channels.${channel.name}`, detail: 'channel added' });
+    }
+  }
+  return changes;
+}

package/src/diff-entities.ts

@@ -115,10 +115,17 @@ function diffColumns(
   const beforeColumns = index(before.columns, (c) => c.name);
   for (const column of after.columns) {
     if (!beforeColumns.has(column.name)) {
+      // A default is what makes a NOT NULL column safe to add: every existing row takes it and no
+      // writer that omits the column is refused.
+      const additive = column.nullable || column.hasDefault === true;
       changes.push({
-        kind: column.nullable ? 'additive' : 'breaking',
+        kind: additive ? 'additive' : 'breaking',
         path: `${path}.columns.${column.name}`,
-        detail: column.nullable ? 'column added' : 'NOT NULL column added with no default',
+        detail: column.nullable
+          ? 'column added'
+          : additive
+            ? 'column added with a default'
+            : 'NOT NULL column added with no default',
       });
     }
   }

package/src/diff-operations.ts

@@ -1,4 +1,5 @@
-// The two callable surfaces — actions and queries — and the permissions they require.
+// The two callable surfaces — actions and queries — and the permissions they require. The
+// permission rule is exported: a channel's subscribe requires permissions the same way.
 
 import { canonicalJson, isMcpExposed } from '@ultimat3/core';
 import type { ManifestChange } from './diff-change';
@@ -6,6 +7,11 @@ import { diffScalar, index } from './diff-change';
 import { diffRateLimit } from './diff-rate-limit';
 import type { ActionFact, QueryFact } from './schema';
 
+/** Any fact that names the permissions it requires — an action, a query, a channel. */
+export interface PermissionBearing {
+  readonly permissions: readonly string[];
+}
+
 export function diffActions(
   before: readonly ActionFact[],
   after: readonly ActionFact[],
@@ -165,10 +171,10 @@ export function diffQueries(
  * (`and(post:publish, org:administer)`) equals no permission, so a rule reading it would call
  * every non-trivially-guarded operation unchanged while both of its real grants moved.
  */
-function diffPermissions(
+export function diffPermissions(
   path: string,
-  before: ActionFact | QueryFact,
-  after: ActionFact | QueryFact,
+  before: PermissionBearing,
+  after: PermissionBearing,
 ): readonly ManifestChange[] {
   const declared = readPermissions(before);
   const next = readPermissions(after);
@@ -204,7 +210,7 @@ function diffPermissions(
 }
 
 /** The list as the FILE carries it, or `undefined` when it carries nothing this can compare. */
-function readPermissions(fact: ActionFact | QueryFact): readonly string[] | undefined {
+function readPermissions(fact: PermissionBearing): readonly string[] | undefined {
   const value: unknown = fact.permissions;
   if (!Array.isArray(value)) return undefined;
   return value.every((entry) => typeof entry === 'string')

package/src/diff.ts

@@ -13,6 +13,7 @@
 
 import type { ManifestChange } from './diff-change';
 import { diffNamedSet } from './diff-change';
+import { diffChannels } from './diff-channels';
 import { diffEntities } from './diff-entities';
 import { diffActions, diffQueries } from './diff-operations';
 import { diffErrorCodes, diffPolicies } from './diff-registries';
@@ -46,6 +47,8 @@ export function diffManifest(before: Manifest, after: Manifest): ManifestDiff {
 
   changes.push(...diffActions(before.actions, after.actions));
   changes.push(...diffQueries(before.queries, after.queries));
+  // `?? []`: a file written before channels were projected carries none, which is not a removal.
+  changes.push(...diffChannels(before.channels ?? [], after.channels ?? []));
   changes.push(...diffRoutes(before.routes, after.routes));
   changes.push(...diffJobs(before.jobs, after.jobs));
   changes.push(...diffTasks(before.tasks, after.tasks));

package/src/emit.ts

@@ -32,6 +32,7 @@ export const KEY_ORDER = [
   'entities',
   'actions',
   'queries',
+  'channels',
   'jobs',
   'tasks',
   'policies',

package/src/index.ts

@@ -16,8 +16,6 @@ export { diffManifest, formatDiff } from './diff';
 export type { DocEntry, DocEntryKind } from './docs-scan';
 export {
   headerComment,
-  parseGuideSections,
-  parseReExports,
   scanInstalledDocs,
   scanPackageDocs,
   shortName,
@@ -44,6 +42,7 @@ export {
 } from './errors';
 export type {
   ActionFact,
+  ChannelFact,
   ColumnFact,
   EntityFact,
   ErrorCodeFact,

package/src/schema.ts

@@ -47,6 +47,12 @@ export interface ColumnFact {
   readonly nullable: boolean;
   readonly primaryKey?: boolean;
   readonly references?: string;
+  /**
+   * The column has a declared default (a value, `defaultNow()`, a generated key). Written only when
+   * true, so a column without one reads as it always did. Adding a NOT NULL column WITH a default
+   * is additive — every existing row takes the default — and was classed breaking without this.
+   */
+  readonly hasDefault?: boolean;
 }
 
 export interface EntityFact {
@@ -110,6 +116,24 @@ export interface QueryFact {
   readonly cacheTags: readonly string[];
 }
 
+/**
+ * A declared realtime `channel()`: what a client subscribes by, and what its policy requires.
+ * Its NAME and PARAMS are the wire contract — a client spells neither, it derives both from the
+ * declaration — so a change to either is breaking for every page built against the old ones.
+ */
+export interface ChannelFact {
+  readonly name: string;
+  readonly params: readonly string[];
+  /** The query a client re-reads on `replay-gap`. */
+  readonly catchUp: string;
+  /** Record types (entity names) the channel carries. */
+  readonly records: readonly string[];
+  readonly events: boolean;
+  /** The policy's label. Never null since 22.0.0 — `channel()` requires a policy. */
+  readonly policy: string;
+  readonly permissions: readonly string[];
+}
+
 export interface JobFact {
   readonly name: string;
   readonly input: JsonValue;
@@ -156,6 +180,11 @@ export interface Manifest {
   readonly entities: readonly EntityFact[];
   readonly actions: readonly ActionFact[];
   readonly queries: readonly QueryFact[];
+  /**
+   * Optional to a READER only: a file written before channels were projected has none, and that
+   * is "no channels", never an unreadable manifest. `buildManifest` always writes it.
+   */
+  readonly channels?: readonly ChannelFact[];
   readonly jobs: readonly JobFact[];
   readonly tasks: readonly TaskFact[];
   readonly policies: readonly PolicyFact[];
@@ -212,6 +241,8 @@ export function isManifest(value: unknown): value is Manifest {
   const m = value as Record<string, unknown>;
   if (typeof m['manifestVersion'] !== 'number' || typeof m['buildId'] !== 'string') return false;
   for (const section of ARRAY_SECTIONS) if (!Array.isArray(m[section])) return false;
+  // Absent is a pre-channel file and readable; present and not an array is a damaged one.
+  if (m['channels'] !== undefined && !Array.isArray(m['channels'])) return false;
   return isAppIdentity(m['app']);
 }
 

package/src/sources.ts

@@ -9,6 +9,7 @@ import { describeActions } from '@ultimat3/action';
 import { describeEntities } from '@ultimat3/entity';
 import { describeJobs } from '@ultimat3/jobs';
 import { describeQueries } from '@ultimat3/query';
+import { describeChannels } from '@ultimat3/realtime/server';
 import type { ManifestSources } from './build';
 import type { ErrorCodeFact, JsonValue, PolicyFact, RouteFact, TaskFact } from './schema';
 
@@ -53,6 +54,7 @@ export function frameworkSources(input: FrameworkSourcesInput): ManifestSources
         type: column.kind,
         nullable: !column.notNull,
         primaryKey: column.primaryKey,
+        ...(column.hasDefault ? { hasDefault: true } : {}),
         ...(column.references === null ? {} : { references: column.references }),
       })),
       invariants: entity.invariants.map((invariant) => invariant.name),
@@ -86,6 +88,17 @@ export function frameworkSources(input: FrameworkSourcesInput): ManifestSources
       ...(query.subscribes === null ? {} : { subscribes: query.subscribes }),
       cacheTags: query.tags,
     })),
+    // Already the fact's shape, sorted and flattened by `describeChannels` — projected field by
+    // field all the same, for the reason above.
+    channels: describeChannels().map((channel) => ({
+      name: channel.name,
+      params: channel.params,
+      catchUp: channel.catchUp,
+      records: channel.records,
+      events: channel.events,
+      policy: channel.policy,
+      permissions: channel.permissions,
+    })),
     jobs: describeJobs().map((job) => ({
       name: job.name,
       input: asJson(job.input),