foldkit-surface 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -1,15 +1,16 @@
1
1
  import { Optic, Option, Result, Schema } from "effect";
2
2
  //#region src/index.ts
3
3
  /**
4
- * `foldkit-surface` — **Phase 0 inference spike**.
4
+ * `foldkit-surface` — the observation boundary for a Foldkit application.
5
5
  *
6
- * Minimal, deliberately non-final implementations of the Surface and Remote
7
- * descriptors, written only to answer the five inference questions in
8
- * `docs/design/REVISION_PLAN.md` §15 (Phase 0). Runtime behaviour is thin; the deliverable
9
- * is the type surface, pinned by `test/inference.test-d.ts`.
6
+ * A Surface is a pure projection of the Model: it declares which fields a
7
+ * feature reads and which Messages it may construct, from the application's
8
+ * own Schema rather than a second hand-written interface. `foldkit-remote`,
9
+ * `foldkit-sync`, `foldkit-agent`, and `foldkit-mirror` all read this boundary,
10
+ * and `Module` validates that each Model path has one owner.
10
11
  *
11
- * Phase 1 replaces the Surface half with the real package. Phase 3 moves the
12
- * Entity/Selection/Remote half into `foldkit-remote`.
12
+ * Nothing here runs: the deliverable is the type surface, pinned by
13
+ * `test/inference.test-d.ts`.
13
14
  */
14
15
  /**
15
16
  * Low-level escape hatch for a focus with no Model path of its own. Prefer the
@@ -84,7 +85,7 @@ function makeTree(schema, path, optic, get, optional = false, set, owner) {
84
85
  }, owner);
85
86
  node.select = (projection) => {
86
87
  const dependencies = mergeDependencies([path, ...projection.dependencies]);
87
- return optional ? makeProjection(Schema.Option(projection.Model), dependencies, projection.requirements, (root) => Option.map(get(root), (value) => projection.read(value)), projection.connections) : makeProjection(projection.Model, dependencies, projection.requirements, (root) => projection.read(get(root)), projection.connections);
88
+ return optional ? makeProjection(Schema.Option(projection.Model), dependencies, (root) => Option.map(get(root), (value) => projection.read(value)), projection.metadata) : makeProjection(projection.Model, dependencies, (root) => projection.read(get(root)), projection.metadata);
88
89
  };
89
90
  return node;
90
91
  }
@@ -100,94 +101,59 @@ function mergeDependencies(dependencies) {
100
101
  }
101
102
  return merged;
102
103
  }
103
- const windowKey = (window) => JSON.stringify([
104
- window.first ?? null,
105
- window.last ?? null,
106
- window.after ?? null,
107
- window.before ?? null
108
- ]);
109
- /**
110
- * Merges connection requirements for the same connection and window into one,
111
- * unioning what they select of each item; the first keeps its other properties.
112
- */
113
- function mergeConnections(connections) {
114
- const merged = /* @__PURE__ */ new Map();
115
- for (const connection of connections) {
116
- const key = `${connection.identity}\u0000${windowKey(connection.window)}`;
117
- const current = merged.get(key);
118
- merged.set(key, current === void 0 ? connection : {
119
- ...current,
120
- select: mergeRelation(current.select, connection.select)
121
- });
122
- }
123
- return [...merged.values()];
124
- }
125
- /** Unions two relation slices for the same target: fields, windows, and nested relations. */
126
- function mergeRelation(current, next) {
127
- const fields = [...current.fields];
128
- const seen = new Set(fields);
129
- for (const field of next.fields) {
130
- if (seen.has(field)) continue;
131
- seen.add(field);
132
- fields.push(field);
133
- }
134
- const windows = {
135
- ...current.windows,
136
- ...next.windows
137
- };
138
- const relations = mergeRelations(current.relations, next.relations);
139
- return {
140
- entity: current.entity,
141
- fields,
142
- ...Object.keys(windows).length === 0 ? {} : { windows },
143
- ...relations === void 0 ? {} : { relations }
144
- };
145
- }
146
- /** Unions two relation maps field by field; a field in both merges recursively. */
147
- function mergeRelations(current, next) {
148
- if (current === void 0) return next;
149
- if (next === void 0) return current;
150
- const merged = { ...current };
151
- for (const [field, relation] of Object.entries(next)) {
152
- const existing = merged[field];
153
- merged[field] = existing === void 0 ? relation : mergeRelation(existing, relation);
154
- }
155
- return merged;
156
- }
157
- /** Unions requirements for the same entity + id, dropping duplicate fields. */
158
- function mergeRequirements(requirements) {
104
+ /** Marks a `Metadata` value. Its entries are private to this module. */
105
+ const MetadataTypeId = Symbol.for("foldkit-surface/Metadata");
106
+ const noEntries = /* @__PURE__ */ new Map();
107
+ const noValues = Object.freeze([]);
108
+ const entriesByMetadata = /* @__PURE__ */ new WeakMap();
109
+ const makeMetadata = (entries) => {
110
+ const metadata = Object.freeze(Object.defineProperty({}, MetadataTypeId, { value: MetadataTypeId }));
111
+ entriesByMetadata.set(metadata, entries);
112
+ return metadata;
113
+ };
114
+ const isMetadata = (value) => typeof value === "object" && value !== null && entriesByMetadata.has(value);
115
+ /** A value this module did not make has no entries. */
116
+ const entriesOf = (metadata) => entriesByMetadata.get(metadata) ?? noEntries;
117
+ const emptyMetadata = makeMetadata(noEntries);
118
+ function combineMetadata(parts) {
119
+ if (parts.length === 1) return isMetadata(parts[0]) ? parts[0] : emptyMetadata;
159
120
  const grouped = /* @__PURE__ */ new Map();
160
- for (const requirement of requirements) {
161
- const key = `${requirement.entity}\u0000${requirement.id}`;
121
+ for (const part of parts) for (const [key, values] of entriesOf(part)) {
162
122
  const group = grouped.get(key);
163
- const live = group?.live === true || requirement.live === true;
164
- grouped.set(key, {
165
- ...mergeRelation(group ?? {
166
- entity: requirement.entity,
167
- fields: []
168
- }, requirement),
169
- id: requirement.id,
170
- ...live ? { live } : {}
171
- });
123
+ if (group === void 0) grouped.set(key, [...values]);
124
+ else group.push(...values);
172
125
  }
173
- return [...grouped.values()];
126
+ if (grouped.size === 0) return emptyMetadata;
127
+ const merged = /* @__PURE__ */ new Map();
128
+ for (const [key, values] of grouped) merged.set(key, Object.freeze([...key.merge(values)]));
129
+ return makeMetadata(merged);
174
130
  }
175
- /**
176
- * Requirement helpers, for the packages that plan and serve requirements.
177
- * `merge` unions same-entity+id requirements; `mergeRelation` unions two
178
- * slices of one target (fields, windows, nested relations).
179
- */
180
- const Requirement = {
181
- merge: mergeRequirements,
182
- mergeRelation,
183
- mergeConnections
131
+ const Metadata = {
132
+ /**
133
+ * Declares an interpreter's slot. Call once per package, at module level:
134
+ * entries are found by the key object, so two copies of a package (a
135
+ * duplicated install, a reloaded module) do not see each other's entries.
136
+ */
137
+ key: (name, options) => {
138
+ const key = {
139
+ name,
140
+ merge: options.merge,
141
+ summarize: options.summarize,
142
+ of: (...values) => values.length === 0 ? emptyMetadata : makeMetadata(/* @__PURE__ */ new Map([[key, Object.freeze([...key.merge(values)])]])),
143
+ get: (metadata) => entriesOf(metadata).get(key) ?? noValues
144
+ };
145
+ return key;
146
+ },
147
+ summarize: (metadata) => [...entriesOf(metadata)].map(([key, values]) => ({
148
+ name: key.name,
149
+ entries: values.map((value) => key.summarize(value))
150
+ }))
184
151
  };
185
- function makeProjection(Model, dependencies, requirements, read, connections = []) {
152
+ function makeProjection(Model, dependencies, read, metadata = emptyMetadata) {
186
153
  return {
187
154
  Model,
188
155
  dependencies,
189
- requirements,
190
- connections,
156
+ metadata,
191
157
  read
192
158
  };
193
159
  }
@@ -203,8 +169,7 @@ const Projection = {
203
169
  of: (schema) => (selection) => {
204
170
  const picked = {};
205
171
  const dependencies = [];
206
- const requirements = [];
207
- const connections = [];
172
+ const metadata = [];
208
173
  const readers = [];
209
174
  for (const key of Object.keys(selection)) {
210
175
  const choice = selection[key];
@@ -215,8 +180,7 @@ const Projection = {
215
180
  const nested = choice;
216
181
  picked[key] = nested.Model;
217
182
  dependencies.push(...nested.dependencies);
218
- requirements.push(...nested.requirements);
219
- connections.push(...nested.connections);
183
+ metadata.push(nested.metadata);
220
184
  readers.push([key, (root) => nested.read(propertyReader(root, key))]);
221
185
  }
222
186
  }
@@ -225,21 +189,19 @@ const Projection = {
225
189
  for (const [key, reader] of readers) out[key] = reader(root);
226
190
  return out;
227
191
  };
228
- return makeProjection(objectSchema(picked), mergeDependencies(dependencies), mergeRequirements(requirements), read, mergeConnections(connections));
192
+ return makeProjection(objectSchema(picked), mergeDependencies(dependencies), read, combineMetadata(metadata));
229
193
  },
230
194
  struct: (entries) => {
231
195
  const picked = {};
232
196
  const dependencies = [];
233
- const requirements = [];
234
- const connections = [];
197
+ const metadata = [];
235
198
  const readers = [];
236
199
  for (const key of Object.keys(entries)) {
237
200
  const entry = entries[key];
238
201
  if ("dependencies" in entry) {
239
202
  picked[key] = entry.Model;
240
203
  dependencies.push(...entry.dependencies);
241
- requirements.push(...entry.requirements);
242
- connections.push(...entry.connections);
204
+ metadata.push(entry.metadata);
243
205
  readers.push([key, entry.read]);
244
206
  } else {
245
207
  picked[key] = entry.Schema;
@@ -252,7 +214,7 @@ const Projection = {
252
214
  for (const [key, reader] of readers) out[key] = reader(root);
253
215
  return out;
254
216
  };
255
- return makeProjection(objectSchema(picked), mergeDependencies(dependencies), mergeRequirements(requirements), read, mergeConnections(connections));
217
+ return makeProjection(objectSchema(picked), mergeDependencies(dependencies), read, combineMetadata(metadata));
256
218
  },
257
219
  /**
258
220
  * Maps a Projection over an array: `array(p): Projection<ReadonlyArray<Root>,
@@ -262,16 +224,14 @@ const Projection = {
262
224
  array: (projection) => ({
263
225
  Model: Schema.Array(projection.Model),
264
226
  dependencies: projection.dependencies,
265
- requirements: projection.requirements,
266
- connections: projection.connections,
227
+ metadata: projection.metadata,
267
228
  read: (root) => root.map((value) => projection.read(value))
268
229
  }),
269
230
  /** Maps a Projection inside an Option, preserving absence. */
270
231
  option: (projection) => ({
271
232
  Model: Schema.Option(projection.Model),
272
233
  dependencies: projection.dependencies,
273
- requirements: projection.requirements,
274
- connections: projection.connections,
234
+ metadata: projection.metadata,
275
235
  read: (root) => Option.map(root, (value) => projection.read(value))
276
236
  }),
277
237
  read: (projection, root) => projection.read(root),
@@ -283,8 +243,7 @@ const Projection = {
283
243
  fromReader: (Model, read, options) => ({
284
244
  Model,
285
245
  dependencies: options?.dependencies ?? [],
286
- requirements: options?.requirements ?? [],
287
- connections: options?.connections ?? [],
246
+ metadata: options?.metadata ?? emptyMetadata,
288
247
  read
289
248
  }),
290
249
  /**
@@ -355,7 +314,7 @@ const Projection = {
355
314
  };
356
315
  }
357
316
  };
358
- const isProjection = (value) => typeof value === "object" && value !== null && "read" in value && "requirements" in value;
317
+ const isProjection = (value) => typeof value === "object" && value !== null && typeof value.read === "function" && isMetadata(value.metadata);
359
318
  const makeScope = (config) => {
360
319
  const owner = {};
361
320
  return {
@@ -501,7 +460,7 @@ const Surface = {
501
460
  owns: [],
502
461
  observes: projection.dependencies,
503
462
  messages: surface.messages.map(messageTag).filter((tag) => tag !== void 0),
504
- requirements: projection.requirements
463
+ metadata: Metadata.summarize(projection.metadata)
505
464
  };
506
465
  },
507
466
  /**
@@ -513,12 +472,14 @@ const Surface = {
513
472
  return {
514
473
  name: surface.name,
515
474
  dependencies: projection.dependencies,
516
- requirements: projection.requirements,
475
+ metadata: Metadata.summarize(projection.metadata),
517
476
  emits: surface.messages
518
477
  };
519
478
  }
520
479
  };
521
480
  const label = (contract) => `${contract.kind}:${contract.name}`;
481
+ /** Metadata summaries are application data (a query's input), so they cannot break the table. */
482
+ const tableCell = (text) => text.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r\n?|\n/g, " ");
522
483
  const pathKey = (path) => path.join(".");
523
484
  const isPrefix = (prefix, path) => prefix.length <= path.length && prefix.every((segment, index) => segment === path[index]);
524
485
  const toContract = (item) => "contract" in item ? item.contract : "projection" in item ? Surface.contract(item, void 0) : item;
@@ -650,8 +611,8 @@ const Module = {
650
611
  const owner = row.owner === void 0 ? "LOCAL" : `${row.owner.kind.toUpperCase()} ${row.owner.name}`;
651
612
  lines.push(`${last ? "└── " : "├── "}${pathKey(row.path).padEnd(width)} ${owner}`);
652
613
  });
653
- lines.push("```", "", "| Contract | Owns | Observes | Messages | Requirements |", "| --- | --- | --- | --- | --- |");
654
- for (const contract of manifest.contracts) lines.push(`| ${contract.kind}:${contract.name} | ${contract.owns.map(pathKey).join(", ")} | ${contract.observes.map(pathKey).join(", ")} | ${contract.messages.join(", ")} | ${contract.requirements.map((r) => `${r.entity}:${r.id}`).join(", ")} |`);
614
+ lines.push("```", "", "| Contract | Owns | Observes | Messages | Metadata |", "| --- | --- | --- | --- | --- |");
615
+ for (const contract of manifest.contracts) lines.push(`| ${contract.kind}:${contract.name} | ${contract.owns.map(pathKey).join(", ")} | ${contract.observes.map(pathKey).join(", ")} | ${contract.messages.join(", ")} | ${tableCell(contract.metadata.map((summary) => `${summary.name}: ${summary.entries.join(", ")}`).join("; "))} |`);
655
616
  if (manifest.findings.length > 0) {
656
617
  lines.push("", "## Findings", "");
657
618
  for (const finding of manifest.findings) lines.push(`- **${finding.rule}** ${finding.message}`);
@@ -686,6 +647,6 @@ const Module = {
686
647
  }
687
648
  };
688
649
  //#endregion
689
- export { MessageSet, ModelRef, Module, Projection, Requirement, Surface };
650
+ export { MessageSet, Metadata, MetadataTypeId, ModelRef, Module, Projection, Surface };
690
651
 
691
652
  //# sourceMappingURL=index.mjs.map