@fougere/core 0.11.0-alpha.0 → 0.12.1-alpha.0

package/src/wire/Page.ts

@@ -0,0 +1,50 @@
+/**
+ * What a paged operation answers — the rows, and what the storage said about the rest of them.
+ *
+ * An ENVELOPE rather than the array `Storage.list` hands back: that one carries `total` and
+ * `hasMore` as properties OF the array, and `JSON.stringify` keeps only the indices. Measured
+ * 2026-09-18 — `page.total` is 42 in this process and `undefined` behind `fronds:`, off the same
+ * code. What crosses has to be named, so it is a field.
+ *
+ * `Storage.list` keeps its array: it answers inside a frond and never crosses.
+ */
+export interface Page<Row> {
+  items: Row[];
+  /** Only when the caller asked to count. */
+  total?: number;
+  hasMore?: boolean;
+  endCursor?: string;
+}
+
+/**
+ * The array `Storage.list` answers, read as the page an operation hands over.
+ *
+ * A storage handed in by a host may answer the envelope already — `storageFactory` is its door,
+ * and nothing there is obliged to subclass an array. Taken as it comes in that case.
+ */
+export function pageOf<Row>(rows: Page<Row> | readonly Row[]): Page<Row> {
+  if (!Array.isArray(rows)) return rows as Page<Row>;
+
+  const { total, hasMore, endCursor } = rows as unknown as Omit<Page<Row>, 'items'>;
+
+  return {
+    items: [...rows],
+    ...(total !== undefined && { total }),
+    ...(hasMore !== undefined && { hasMore }),
+    ...(endCursor !== undefined && { endCursor }),
+  };
+}
+
+/**
+ * The value read as a page, or nothing.
+ *
+ * Read from the FORM, and arbitrated by the schema: an entity legally declaring a field named
+ * `items` answers a row, not a page, and it is the only thing that could tell the two apart.
+ */
+export function asPage(value: unknown, fields: Record<string, unknown>): Page<unknown> | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  if ('items' in fields) return undefined;
+  const page = value as Page<unknown>;
+
+  return Array.isArray(page.items) ? page : undefined;
+}

package/src/wire/Signature.ts

@@ -10,4 +10,11 @@ export interface Signature {
   inherited?: boolean;
   /** The operation in words — the first sentence of the method's doc comment. */
   description?: string;
+  /**
+   * The first thing in the return type that is not data — its path, and the type sitting there.
+   *
+   * Written whenever a checker read the signature, and judged only where nothing converts the
+   * output: what a declared entity answers is encoded by its fields.
+   */
+  notData?: string;
 }

package/src/wire/binding.ts

@@ -48,66 +48,34 @@ export function computeBindingPlan(
   params: Param[],
   collectorTypeNames: Set<string>,
 ): BindingPlan {
-  return params.map((param) => {
-    const typeName = param.type.name;
-    // `lowerFirst`, never `toLowerCase()`: the collector set is keyed the way the
-    // scan spells it, and the two agree on one word only — `AuthorUser` looked up as
-    // `authoruser` missed `authorUser` and fell through to branch 4, the request input.
-    const typeKey = lowerFirst(typeName);
-
-    // 0. Fact, or the same fact before it is final. Both name themselves, so nothing has
-    //    to be known in advance, and they come FIRST because branch 4 would otherwise hand
-    //    either the caller's input under the name of something that happened.
-    const announced = param.type.name === 'Fact' || param.type.name === 'Pipe'
-      ? param.type.generics?.[0]?.name
-      : undefined;
-    if (announced) {
-      return {
-        name: param.name,
-        source: {
-          kind: (param.type.name === 'Pipe' ? 'pipe' : 'fact') as 'pipe' | 'fact',
-          factName: lowerFirst(announced),
-        },
-        optional: param.optional ?? false,
-      };
-    }
+  return params.map((param) => ({
+    name: param.name,
+    source: sourceOf(param, collectorTypeNames),
+    optional: param.optional ?? false,
+  }));
+}
 
-    // 1. Collector — param type matches a type some collector answers for
-    if (collectorTypeNames.has(typeKey)) {
-      return {
-        name: param.name,
-        source: { kind: 'collector' as const, typeName: typeKey },
-        optional: param.optional ?? false,
-      };
-    }
+/**
+ * Where ONE parameter gets its value, in the order the branches must be asked.
+ *
+ * A fact and a link name themselves, so they come FIRST: asked later, the last branch would hand
+ * the caller's input under the name of something that happened.
+ */
+function sourceOf(param: Param, collectorTypeNames: Set<string>): ParamSource {
+  const typeName = param.type.name;
+  // `lowerFirst`, never `toLowerCase()`: the collector set is keyed the way the scan spells it,
+  // and the two agree on one word only — `AuthorUser` looked up as `authoruser` missed
+  // `authorUser` and fell through to the request input.
+  const typeKey = lowerFirst(typeName);
 
-    // 2. InvocationContext — inject the full context
-    if (typeName === 'InvocationContext') {
-      return {
-        name: param.name,
-        source: { kind: 'context' as const },
-        optional: param.optional ?? false,
-      };
-    }
+  const announced = typeName === 'Fact' || typeName === 'Pipe' ? param.type.generics?.[0]?.name : undefined;
+  if (announced) {
+    return { kind: typeName === 'Pipe' ? 'pipe' : 'fact', factName: lowerFirst(announced) };
+  }
 
-    // 3. Primitives — matched by name from params > query
-    if (PRIMITIVES.has(typeName)) {
-      return {
-        name: param.name,
-        source: {
-          kind: 'param' as const,
-          name: param.name,
-          coerce: coercionFor(typeName),
-        },
-        optional: param.optional ?? false,
-      };
-    }
+  if (collectorTypeNames.has(typeKey)) return { kind: 'collector', typeName: typeKey };
+  if (typeName === 'InvocationContext') return { kind: 'context' };
+  if (PRIMITIVES.has(typeName)) return { kind: 'param', name: param.name, coerce: coercionFor(typeName) };
 
-    // 4. Everything else — input
-    return {
-      name: param.name,
-      source: { kind: 'input' as const },
-      optional: param.optional ?? false,
-    };
-  });
+  return { kind: 'input' };
 }

package/src/wire/drift.ts

@@ -15,8 +15,14 @@ export interface CardDrift {
 }
 
 /** Every facade of a card, by name. */
-function facadesOf(card: IdentityCard, frond: string): Map<string, { ops: Set<string>; schema?: SchemaDescriptor }> {
-  const found = new Map<string, { ops: Set<string>; schema?: SchemaDescriptor }>();
+/** What a door of that card answers, and the shape of the row it hands back. */
+interface Answering {
+  ops: Set<string>;
+  schema?: SchemaDescriptor;
+}
+
+function facadesOf(card: IdentityCard, frond: string): Map<string, Answering> {
+  const found = new Map<string, Answering>();
   for (const one of card.fronds) {
     if (one.name !== frond) continue;
     for (const facade of one.facades) {
@@ -37,37 +43,58 @@ function factsOf(card: IdentityCard, frond: string): Map<string, SchemaDescripto
 
 /** What a consumer's synced copy no longer matches in what the producer serves. */
 export function driftOf(mine: IdentityCard, theirs: IdentityCard, frond: string): CardDrift {
-  const mineFacades = facadesOf(mine, frond);
-  const served = facadesOf(theirs, frond);
   const drift: CardDrift = { frond, missingDoors: [], missingOps: [], shapes: [], facts: [] };
 
-  for (const [name, facade] of mineFacades) {
-    const there = served.get(name);
-    if (!there) { drift.missingDoors.push(name); continue; }
+  driftInDoors(facadesOf(mine, frond), facadesOf(theirs, frond), drift);
+  driftInFacts(factsOf(mine, frond), factsOf(theirs, frond), drift);
+
+  return drift;
+}
+
+/** A door that is gone, an operation it no longer answers, or a row that changed shape. */
+function driftInDoors(
+  mine: Map<string, Answering>,
+  theirs: Map<string, Answering>,
+  drift: CardDrift,
+): void {
+  for (const [name, facade] of mine) {
+    const there = theirs.get(name);
+    if (!there) {
+      drift.missingDoors.push(name);
+      continue;
+    }
 
     const missing = [...facade.ops].filter((op) => !there.ops.has(op));
     if (missing.length > 0) drift.missingOps.push({ facade: name, ops: missing.sort() });
 
-    if (facade.schema && there.schema) {
-      // `Card.diff` never guesses a rename — a field gone plus a field appeared lands in
-      // `ambiguous`, and only a declaration settles it. Here nobody can declare one, so
-      // the pair is reported as it is and a human reads it.
-      const moved = Card.fromDescriptor(facade.schema).diff(Card.fromDescriptor(there.schema));
-      if (moved.changes.length > 0) drift.shapes.push({ facade: name, changes: moved.changes });
-    }
+    if (!facade.schema || !there.schema) continue;
+
+    // `Card.diff` never guesses a rename — a field gone plus a field appeared lands in
+    // `ambiguous`, and only a declaration settles it. Here nobody can declare one, so the
+    // pair is reported as it is and a human reads it.
+    const moved = Card.fromDescriptor(facade.schema).diff(Card.fromDescriptor(there.schema));
+    if (moved.changes.length > 0) drift.shapes.push({ facade: name, changes: moved.changes });
   }
+}
+
+/** A fact nobody announces any more, or one whose payload moved under its readers. */
+function driftInFacts(
+  mine: Map<string, SchemaDescriptor | undefined>,
+  theirs: Map<string, SchemaDescriptor | undefined>,
+  drift: CardDrift,
+): void {
+  for (const [name, shape] of mine) {
+    if (!theirs.has(name)) {
+      drift.facts.push({ fact: name, changes: 'gone' });
+      continue;
+    }
 
-  const heldFacts = factsOf(mine, frond);
-  const servedFacts = factsOf(theirs, frond);
-  for (const [name, shape] of heldFacts) {
-    if (!servedFacts.has(name)) { drift.facts.push({ fact: name, changes: 'gone' }); continue; }
-    const there = servedFacts.get(name);
+    const there = theirs.get(name);
     if (!shape || !there) continue;
+
     const moved = Card.fromDescriptor(shape).diff(Card.fromDescriptor(there));
     if (moved.changes.length > 0) drift.facts.push({ fact: name, changes: moved.changes });
   }
-
-  return drift;
 }
 
 /** Whether anything at all separates the two cards. */