@ultimat3/manifest 20.2.0 → 21.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/manifest",
-  "version": "20.2.0",
+  "version": "21.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.0",
-    "@ultimat3/core": "20.2.0",
-    "@ultimat3/entity": "20.2.0",
-    "@ultimat3/jobs": "20.2.0",
-    "@ultimat3/query": "20.2.0"
+    "@ultimat3/action": "21.0.0",
+    "@ultimat3/core": "21.0.0",
+    "@ultimat3/entity": "21.0.0",
+    "@ultimat3/jobs": "21.0.0",
+    "@ultimat3/query": "21.0.0",
+    "@ultimat3/realtime": "21.0.0"
   }
 }

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 ?? 'none'} -> ${next.policy ?? 'none'}`,
+      });
+    }
+    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-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

@@ -44,6 +44,7 @@ export {
 } from './errors';
 export type {
   ActionFact,
+  ChannelFact,
   ColumnFact,
   EntityFact,
   ErrorCodeFact,

package/src/schema.ts

@@ -110,6 +110,23 @@ 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;
+  readonly policy: string | null;
+  readonly permissions: readonly string[];
+}
+
 export interface JobFact {
   readonly name: string;
   readonly input: JsonValue;
@@ -156,6 +173,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 +234,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';
 
@@ -86,6 +87,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),