@ultimat3/manifest 21.0.0 → 22.1.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": "21.0.0",
+  "version": "22.1.0",
   "description": "x.manifest.json: deterministic generated facts, contract diff, AGENTS.md budget",
   "license": "MIT",
   "type": "module",
@@ -31,11 +31,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@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"
+    "@ultimat3/action": "22.1.0",
+    "@ultimat3/core": "22.1.0",
+    "@ultimat3/entity": "22.1.0",
+    "@ultimat3/jobs": "22.1.0",
+    "@ultimat3/query": "22.1.0",
+    "@ultimat3/realtime": "22.1.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/diff-channels.ts

@@ -30,7 +30,7 @@ export function diffChannels(
       changes.push({
         kind: 'breaking',
         path: `${path}.policy`,
-        detail: `policy ${channel.policy ?? 'none'} -> ${next.policy ?? 'none'}`,
+        detail: `policy ${channel.policy} -> ${next.policy}`,
       });
     }
     changes.push(...diffPermissions(path, channel, next));

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/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,

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 {
@@ -123,7 +129,8 @@ export interface ChannelFact {
   /** Record types (entity names) the channel carries. */
   readonly records: readonly string[];
   readonly events: boolean;
-  readonly policy: string | null;
+  /** The policy's label. Never null since 22.0.0 — `channel()` requires a policy. */
+  readonly policy: string;
   readonly permissions: readonly string[];
 }
 

package/src/sources.ts

@@ -54,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),