yarramate 1.19.1 → 1.21.0

package/dist/adapters/likec4-prepare.js

@@ -141,7 +141,7 @@ export function prepareLikeC4Export(input) {
             };
         }
     }
-    const projectionResult = evaluateProjection(compilation.graph, projection.projection, compilation.profileContext);
+    const projectionResult = evaluateProjection(compilation.graph, projection.projection, compilation.profileContext, compilation.patternMemberships);
     const comparison = input.comparison === undefined
         ? undefined
         : compareArchitectureStates(compilation.graph, input.comparison.from, input.comparison.to);

package/dist/adapters/visual/protocol-contract.d.ts

@@ -9,6 +9,7 @@
  * `node:path`, or the schema documents into its bundle.
  */
 import type { CanvasGraph } from "../../graph-projection.js";
+import type { NestingKind } from "../../nesting.js";
 import type { YarramateApplyResult, YarramateOperation } from "../../operations.js";
 import type { ProjectionDefinition, ProjectionExclusion, ProjectionQuery } from "../../projection.js";
 /**
@@ -163,6 +164,20 @@ export interface VisualKindOption {
 }
 export interface VisualFilterQueryPayload {
     readonly query: ProjectionQuery;
+    /**
+     * The nesting the canvas is drawing with, when the browser knows it (#473
+     * phase 2).
+     *
+     * Only `query.instances` reads it, and it must: the closure of an instance IS
+     * the containment tree, so evaluating it under a different nesting than the
+     * canvas answers a different question. On the ApertureX reference that is 15
+     * subjects against 2.
+     *
+     * Optional, so an older browser and every filter that names no instance keep
+     * working unchanged; absent, the evaluator falls back to the default nesting
+     * exactly as it did before.
+     */
+    readonly nesting?: readonly NestingKind[];
 }
 export interface VisualFilterResultPayload {
     readonly query: ProjectionQuery;
@@ -250,6 +265,19 @@ export interface VisualChangesetCommitPayload {
 export interface VisualLayoutSavePayload {
     readonly projectionId: string;
     readonly positions: VisualLayoutPositions;
+    /**
+     * What this view folds, saved beside the positions in ONE document (#473).
+     *
+     * Full state every time, never a patch. A half-applied fold state draws a
+     * box whose contents are somewhere else on the canvas, and the sidecar is
+     * written by a browser that may have been reloaded between any two saves.
+     *
+     * `unfolded` exists because the view's own `presentation.fold` is a default,
+     * not a rule: a reader who opened a box must not have it close again when the
+     * default is read back.
+     */
+    readonly folded?: readonly string[];
+    readonly unfolded?: readonly string[];
 }
 /**
  * Terminal event payload. Every reason is the runtime's to choose: only it

package/dist/adapters/visual/session-server.js

@@ -456,14 +456,15 @@ export const startVisualServer = async (options) => {
     // like a broken saved view above — presentation state must never fail a
     // session.
     const layoutDir = resolve(options.cwd, ".yarramate/visual-layout");
-    const layouts = (() => {
-        const built = {};
+    const { layouts, folds } = (() => {
+        const layouts = {};
+        const folds = {};
         let entries;
         try {
             entries = readdirSync(layoutDir);
         }
         catch {
-            return built;
+            return { layouts, folds };
         }
         for (const entry of entries) {
             if (extname(entry) !== ".yaml" && extname(entry) !== ".yml")
@@ -474,13 +475,22 @@ export const startVisualServer = async (options) => {
                 if (!validateVisualLayout(parsed))
                     continue;
                 const sidecar = parsed;
-                built[sidecar.projectionId] = sidecar.positions;
+                layouts[sidecar.projectionId] = sidecar.positions;
+                // A sidecar written before #473 has neither list, and says nothing
+                // about folding rather than saying "fold nothing" - the view's own
+                // default decides for it. Only a sidecar that STATES a fold overrides.
+                if (sidecar.folded !== undefined || sidecar.unfolded !== undefined) {
+                    folds[sidecar.projectionId] = {
+                        folded: [...(sidecar.folded ?? [])],
+                        unfolded: [...(sidecar.unfolded ?? [])],
+                    };
+                }
             }
             catch {
                 // Skipped sidecar: presentation state must never fail a session.
             }
         }
-        return built;
+        return { layouts, folds };
     })();
     // `request.initialModel.graph` is the caller's compile (`buildVisualModelGraph`,
     // before invoking `yarramate-visual start`) and is only the fallback below:
@@ -494,6 +504,7 @@ export const startVisualServer = async (options) => {
         documents: [],
         vocabulary: { conceptKinds: [], relationshipKinds: [] },
         layouts,
+        ...(Object.keys(folds).length === 0 ? {} : { folds }),
         sourceDigests: request.initialModel.sourceDigests,
         // The request's model has no projections in it - `visual-model/v1` carries
         // a graph, not a workspace - so the fallback states nothing rather than
@@ -679,9 +690,15 @@ export const startVisualServer = async (options) => {
         if (!started.ok)
             standingDiagnostics = started.diagnostics;
     }
-    const filterMatchedIds = (query) => compiledWorkspace === undefined
+    const filterMatchedIds = (query, nesting) => compiledWorkspace === undefined
         ? []
-        : matchedIdsOf(compiledWorkspace.graph, query, compiledWorkspace.profileContext);
+        : matchedIdsOf(compiledWorkspace.graph, query, compiledWorkspace.profileContext, 
+        // A view's query can name `instances`, and the facet resolves to the
+        // instance alone without these (ADR 0144).
+        compiledWorkspace.patternMemberships, 
+        // And it resolves the WRONG closure without the nesting the canvas is
+        // drawing with, which is a wrong number rather than a missing one.
+        nesting);
     /**
      * Why a query dropped what it dropped, as the editor's "excluded, and why"
      * list reads it (#248).
@@ -693,9 +710,9 @@ export const startVisualServer = async (options) => {
      * the reason the editor shows and the set the canvas draws cannot come from
      * two readings of the same query.
      */
-    const filterExclusions = (query) => compiledWorkspace === undefined
+    const filterExclusions = (query, nesting) => compiledWorkspace === undefined
         ? []
-        : exclusionsOf(compiledWorkspace.graph, query, compiledWorkspace.profileContext);
+        : exclusionsOf(compiledWorkspace.graph, query, compiledWorkspace.profileContext, compiledWorkspace.patternMemberships, nesting);
     let listening = false;
     let bootstrapSpent = false;
     let agentAttached = false;
@@ -1232,8 +1249,8 @@ export const startVisualServer = async (options) => {
                     kind: "filter-result",
                     result: {
                         query: event.payload.query,
-                        matchedIds: filterMatchedIds(event.payload.query),
-                        excluded: filterExclusions(event.payload.query),
+                        matchedIds: filterMatchedIds(event.payload.query, event.payload.nesting),
+                        excluded: filterExclusions(event.payload.query, event.payload.nesting),
                     },
                 });
                 return;
@@ -1407,7 +1424,7 @@ export const startVisualServer = async (options) => {
                 // never `git commit`ed. It never asks the agent anything, so it is
                 // answered here directly rather than through the pending queue a
                 // poll would drain.
-                const { projectionId, positions } = event.payload;
+                const { projectionId, positions, folded, unfolded } = event.payload;
                 if (!views.some((view) => view.id === projectionId)) {
                     sendFrame(socket, {
                         kind: "layout-save-result",
@@ -1424,10 +1441,26 @@ export const startVisualServer = async (options) => {
                     format: "yarramate/visual-layout/v1",
                     projectionId,
                     positions,
+                    // With the positions, in one document, in full (#473). Same rule
+                    // the local host follows, and it has to be the same rule: a
+                    // sidecar written by one host is read by the other.
+                    ...(folded === undefined ? {} : { folded }),
+                    ...(unfolded === undefined ? {} : { unfolded }),
                 }), "utf8");
                 rendered = {
                     ...rendered,
                     layouts: { ...rendered.layouts, [projectionId]: positions },
+                    ...(folded === undefined && unfolded === undefined
+                        ? {}
+                        : {
+                            folds: {
+                                ...rendered.folds,
+                                [projectionId]: {
+                                    folded: folded ?? [],
+                                    unfolded: unfolded ?? [],
+                                },
+                            },
+                        }),
                 };
                 sendFrame(socket, {
                     kind: "layout-save-result",

package/dist/adapters/visual/wire.d.ts

@@ -1,4 +1,5 @@
 import type { CanvasGraph } from '../../graph-projection.js';
+import type { PatternMembership, PatternVacancy } from '../../compiler.js';
 import type { VISUAL_PROTOCOL_VERSION, VisualApplyResultPayload, VisualAuthority, VisualBrowserInput, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFilterResultPayload, VisualFreezeReason, VisualKindOption, VisualLayoutPositions, VisualLayoutSaveResultPayload, VisualResponse, VisualTerminationReason, VisualViewSummary } from './protocol-contract.js';
 /**
  * Transport shapes the session server and the browser application both speak.
@@ -55,6 +56,28 @@ export interface VisualRenderedModel {
     readonly layouts: {
         readonly [projectionId: string]: VisualLayoutPositions;
     };
+    /**
+     * What each view folds, keyed by projection id (#473). A SIBLING of
+     * `layouts` rather than a field inside its entries: a layout entry is
+     * positions, one shape a host may already be reading, and widening it would
+     * make every reader of `layouts[id]` handle a case that did not exist.
+     */
+    readonly folds?: {
+        readonly [projectionId: string]: {
+            readonly folded: readonly string[];
+            readonly unfolded: readonly string[];
+        };
+    };
+    /**
+     * Which subject fills which slot of which instance (ADR 0131), and which
+     * slots nothing fills (#447), forwarded so the browser can draw containment
+     * and answer "what is inside this box" without a second round trip.
+     *
+     * Optional: a host that never folds and never shows slots need not supply
+     * them, and a frame from before #473 has neither.
+     */
+    readonly memberships?: readonly PatternMembership[];
+    readonly vacancies?: readonly PatternVacancy[];
     /**
      * The sha256 of every workspace source this graph was compiled from, keyed by
      * manifest-relative path — the same map `visual-model/v1` already requires of

package/dist/adapters/visual/workspace-model.d.ts

@@ -2,7 +2,7 @@ import type { Diagnostic } from "../../compiler.js";
 import type { PendingWrite, SourceStore } from "../../source-store.js";
 import type { ResolvedWorkspace } from "../../workspace.js";
 import type { VisualDiagnostic, VisualViewOperation } from "./protocol-contract.js";
-import type { ProjectionDefinition, ProjectionExclusion, ProjectionQuery } from "../../projection.js";
+import type { NestingKind, ProjectionDefinition, ProjectionExclusion, ProjectionQuery } from "../../projection.js";
 import type { ResolvedProfileContext, SemanticGraph } from "../../compiler.js";
 import { type CataloguePatternMembership, type CataloguePatternVacancy } from "../../interrogate-command.js";
 import type { VisualKindOption, VisualViewSummary } from "./protocol-contract.js";
@@ -41,7 +41,7 @@ export declare const kindOptionsOf: (lineages: ReadonlyMap<string, readonly stri
  * subject count. A view over three components with two relationships between
  * them would read as five, and the reviewer counting boxes would find three.
  */
-export declare const conceptCountOf: (graph: SemanticGraph, query: ProjectionQuery, profileContext: ResolvedProfileContext) => number;
+export declare const conceptCountOf: (graph: SemanticGraph, query: ProjectionQuery, profileContext: ResolvedProfileContext, memberships?: readonly CataloguePatternMembership[], nesting?: readonly NestingKind[]) => number;
 /**
  * Folds one interrogation report into what the canvas draws (#292).
  *
@@ -109,9 +109,9 @@ export declare const renderedWorkspaceOf: (compiled: {
     readonly views: readonly VisualViewSummary[];
 };
 /** Every subject a query draws, concepts and relationships alike. */
-export declare const matchedIdsOf: (graph: SemanticGraph, query: ProjectionQuery, profileContext: ResolvedProfileContext) => readonly string[];
+export declare const matchedIdsOf: (graph: SemanticGraph, query: ProjectionQuery, profileContext: ResolvedProfileContext, memberships?: readonly CataloguePatternMembership[], nesting?: readonly NestingKind[]) => readonly string[];
 /** Every concept a query dropped, and the facet that dropped it (#248). */
-export declare const exclusionsOf: (graph: SemanticGraph, query: ProjectionQuery, profileContext: ResolvedProfileContext) => readonly ProjectionExclusion[];
+export declare const exclusionsOf: (graph: SemanticGraph, query: ProjectionQuery, profileContext: ResolvedProfileContext, memberships?: readonly CataloguePatternMembership[], nesting?: readonly NestingKind[]) => readonly ProjectionExclusion[];
 /**
  * One saved view, as the rail reads it. `subjectCount` is the caller's,
  * because counting needs a compiled graph and a session builds its first list

package/dist/adapters/visual/workspace-model.js

@@ -45,7 +45,7 @@ export const kindOptionsOf = (lineages) => [...lineages.keys()].map((id) => ({
  * subject count. A view over three components with two relationships between
  * them would read as five, and the reviewer counting boxes would find three.
  */
-export const conceptCountOf = (graph, query, profileContext) => evaluateProjection(graph, adHoc(query), profileContext).subjects.filter(({ type }) => type === "concept").length;
+export const conceptCountOf = (graph, query, profileContext, memberships, nesting) => evaluateProjection(graph, adHoc(query, nesting), profileContext, memberships).subjects.filter(({ type }) => type === "concept").length;
 export const interrogationOverlayOf = (compiled, 
 /**
  * The catalogue, or the composed SET a workspace carries (#345, ADR 0129).
@@ -118,7 +118,14 @@ dismissed = []) => {
 export const renderedWorkspaceOf = (compiled, views, metadata, catalogue, dismissed) => {
     const refreshedViews = views.map((view) => ({
         ...view,
-        subjectCount: conceptCountOf(compiled.graph, view.query, compiled.profileContext),
+        subjectCount: conceptCountOf(compiled.graph, view.query, compiled.profileContext, 
+        // Without these an `instances` view counts 1 and the rail says so, which
+        // is a wrong number rather than a missing one (ADR 0144).
+        compiled.patternMemberships, 
+        // Each view's OWN nesting, because each view's closure is its own. A rail
+        // sitting beside the canvas must not count a different tree than the
+        // canvas draws.
+        view.presentation?.nesting),
     }));
     const interrogation = catalogue === undefined
         ? undefined
@@ -132,23 +139,39 @@ export const renderedWorkspaceOf = (compiled, views, metadata, catalogue, dismis
                 relationshipKinds: kindOptionsOf(compiled.profileContext.relationshipKindLineages),
             },
             ...(interrogation === undefined ? {} : { interrogation }),
+            // Containment context, forwarded rather than re-derived (#473). Both
+            // hosts build the model here, so local-host and session-server cannot
+            // disagree about what is inside a box - which is the shape of defect
+            // that made `patterns` ship non-functional in 1.4.0, ten source lists
+            // each dropping the same thing.
+            ...(compiled.patternMemberships === undefined
+                ? {}
+                : { memberships: compiled.patternMemberships }),
+            ...(compiled.patternVacancies === undefined
+                ? {}
+                : { vacancies: compiled.patternVacancies }),
         },
         views: refreshedViews,
     };
 };
 /** Every subject a query draws, concepts and relationships alike. */
-export const matchedIdsOf = (graph, query, profileContext) => evaluateProjection(graph, adHoc(query), profileContext).subjects.map(({ id }) => id);
+export const matchedIdsOf = (graph, query, profileContext, memberships, nesting) => evaluateProjection(graph, adHoc(query, nesting), profileContext, memberships).subjects.map(({ id }) => id);
 /** Every concept a query dropped, and the facet that dropped it (#248). */
-export const exclusionsOf = (graph, query, profileContext) => explainProjection(graph, adHoc(query), profileContext);
+export const exclusionsOf = (graph, query, profileContext, memberships, nesting) => explainProjection(graph, adHoc(query, nesting), profileContext, memberships);
 /**
  * A query on its own is not a projection, and every evaluator here wants one.
  * The id is a placeholder that never reaches a document.
  */
-const adHoc = (query) => ({
+const adHoc = (query, nesting) => ({
     format: "yarramate/projection/v1",
     id: "ad-hoc",
     version: "0",
     query,
+    // `query.instances` resolves its closure through the view's nesting, so an
+    // ad-hoc projection that dropped the nesting would answer a DIFFERENT
+    // question than the canvas is drawing: 2 subjects against 15 on the
+    // ApertureX reference, with nothing to say it had (#473 phase 2).
+    ...(nesting === undefined ? {} : { presentation: { nesting } }),
 });
 /**
  * One saved view, as the rail reads it. `subjectCount` is the caller's,

package/dist/adapters/visual-graph-entry.d.ts

@@ -1 +1,2 @@
 export { projectGraphForCanvas, type CanvasGraph, type CanvasNode, type CanvasEdge, } from '../graph-projection.js';
+export { foldTree, foldGraph, nestingTree, liftedEdgeId, NESTING_KIND_IDS, type FoldInput, type FoldNode, type FoldEdge, type FoldMembership, type FoldTree, type LiftedEdge, type NestingConflict, type SlotWiring, } from '../fold-tree.js';

package/dist/adapters/visual-graph-entry.js

@@ -1 +1,7 @@
 export { projectGraphForCanvas, } from '../graph-projection.js';
+// What contains what, and what a fold draws instead (#473). Published here
+// rather than only on the canvas because a host that never renders still has to
+// answer both: an interview counts open questions per box, a report says what
+// an application is made of. `fold-tree.ts` imports nothing, so this subpath
+// stays runtime-neutral.
+export { foldTree, foldGraph, nestingTree, liftedEdgeId, NESTING_KIND_IDS, } from '../fold-tree.js';

package/dist/ask-command.js

@@ -784,7 +784,7 @@ export function runAskCommand(options, cwd) {
                 });
                 if (!loaded.ok)
                     continue;
-                const membership = evaluateProjection(graph, loaded.projection, compilation.profileContext);
+                const membership = evaluateProjection(graph, loaded.projection, compilation.profileContext, compilation.patternMemberships);
                 for (const subject of membership.subjects) {
                     covered.add(subject.id);
                 }
@@ -857,7 +857,7 @@ export function runAskCommand(options, cwd) {
             });
             if (!loaded.ok)
                 return failed(loaded.diagnostics);
-            const evaluated = evaluateProjection(graph, loaded.projection, compilation.profileContext);
+            const evaluated = evaluateProjection(graph, loaded.projection, compilation.profileContext, compilation.patternMemberships);
             const result = {
                 format: 'yarramate/ask-result/v1',
                 workspace: workspace.id,

package/dist/check-command.js

@@ -214,7 +214,18 @@ export function runCheckCommand(options, cwd) {
         // does not build would bury the real failure under its consequences.
         const referenceDiagnostics = result.ok
             ? loadedProjections.flatMap(({ source, loaded }) => loaded.ok
-                ? projectionReferenceDiagnostics(source, loaded.projection, result.graph, result.profileContext)
+                ? projectionReferenceDiagnostics(source, loaded.projection, result.graph, result.profileContext, 
+                // Instance-hood from BOTH lists. A membership row exists only
+                // for a BOUND slot, so an instance whose slots are all empty
+                // has none - and judging it by bindings alone would call a real
+                // instance "not an instance" on the day it was authored, before
+                // anything was wired into it. The honest question is not "did
+                // it bind anything" but "does the model know it as an
+                // instance" (rule 2).
+                new Set([
+                    ...(result.patternMemberships ?? []).map(({ instance }) => instance),
+                    ...(result.patternVacancies ?? []).map(({ instance }) => instance),
+                ]))
                 : [])
             : [];
         const optionalDiagnostics = sortDiagnostics([

package/dist/compiler.d.ts

@@ -108,6 +108,27 @@ export interface PatternMembership {
     readonly slot: string;
     readonly instance: string;
     readonly pattern: string;
+    /**
+     * How the pattern's WIRING relates this slot to the instance (#473).
+     *
+     * - `owned` — a wire runs `self -> slot`. The instance holds the member out:
+     *   it is a part, and a view that folds instances may draw it inside.
+     * - `context` — a wire runs `slot -> self`. The member acts on the instance
+     *   rather than belonging to it: the upstream API it calls, the plane it runs
+     *   on. Folding these would swallow half the landscape into whichever box
+     *   happened to name it.
+     * - `unwired` — the pattern declares the slot and wires nothing through it.
+     *   Still a part; nothing about containment changes.
+     *
+     * A slot with wires in BOTH directions is `owned`: the instance holding
+     * something out is the stronger statement, and it is what a reader means by
+     * the box.
+     *
+     * Optional, so no existing reader breaks. `yarramate/graph/v2` is unchanged:
+     * this is compile CONTEXT like the rest of membership (ADR 0131), never a
+     * claim an author could have written.
+     */
+    readonly wiring?: 'owned' | 'context' | 'unwired';
 }
 /**
  * One slot of one pattern instance that nothing is bound into (#447): the

package/dist/compiler.js

@@ -6,6 +6,24 @@ import { ATTESTATION_PREDICATE_PREFIX, attestationClaimValue } from './graph-cla
 import { shippedPolicyIdentity, shippedPolicySource, } from './shipped-profile.js';
 import { validateDocument, validateProfile, validatePattern } from './schema-validation.js';
 const coreProfile = 'yarramate/core@0.1';
+/**
+ * Which way the pattern's wiring runs between an instance and one of its slots
+ * (#473). Read from the pattern rather than from the graph, because it is a
+ * fact about the SHAPE and holds whether or not the slot is bound.
+ */
+const slotWiringOf = (pattern, slot) => {
+    let held = false;
+    let acts = false;
+    for (const wire of pattern.wiring) {
+        if (wire.from === 'self' && wire.to === slot)
+            held = true;
+        if (wire.from === slot && wire.to === 'self')
+            acts = true;
+    }
+    // Both directions is `owned`: holding something out is the stronger claim,
+    // and it is what a reader means by drawing the box around it.
+    return held ? 'owned' : acts ? 'context' : 'unwired';
+};
 const immutableMap = (entries) => {
     const backing = new Map(entries);
     const facade = {
@@ -2471,6 +2489,7 @@ function compileWorkspaceResolved(parsed) {
         slot,
         instance,
         pattern: pattern.kindIdentity,
+        wiring: slotWiringOf(pattern, slot),
     })))
         .sort((left, right) => left.member.localeCompare(right.member) ||
         left.pattern.localeCompare(right.pattern) ||

package/dist/export-command.js

@@ -250,7 +250,10 @@ export function runExportCommand(options, cwd) {
             });
             if (!loadedProjection.ok)
                 return failed(loadedProjection.diagnostics);
-            result = evaluateProjection(compilation.graph, loadedProjection.projection, compilation.profileContext);
+            result = evaluateProjection(compilation.graph, loadedProjection.projection, compilation.profileContext, 
+            // An AUTHORED projection can name `instances`, and the facet resolves
+            // to the instance alone without these (ADR 0144).
+            compilation.patternMemberships);
         }
         if (kind === 'xlsx') {
             // A workbook an architect can work in (#355). It takes a PROJECTION,

package/dist/fold-tree.d.ts

@@ -0,0 +1,169 @@
+/**
+ * What contains what on a canvas, and what a folded container draws instead of
+ * its contents (#473).
+ *
+ * Two questions, one module, because they are the same question asked twice. A
+ * VIEW says which relationships nest (ADR 0101); a PATTERN says which subjects
+ * are parts of an instance (ADR 0123). Both produce a parent-of map over the
+ * same node ids, and folding reads that one map. Answering them apart would
+ * mean two trees that can disagree about who owns a node.
+ *
+ * Imports nothing but the `NestingKind` type, and that from `./nesting.js`,
+ * which itself imports nothing. The same weight argument that split
+ * `nesting.ts` out of `projection.ts` applies here and harder: this module is
+ * reached from `yarramate/adapter/visual-graph`, the runtime-neutral subpath a
+ * Durable Object imports, where `node:module` and Ajv are not available at any
+ * price. `test/visual-app-browser-safety.test.ts` is what holds that line.
+ *
+ * Everything here is a pure function over plain data. The canvas adapts its own
+ * shapes to {@link FoldInput}; nothing in this file knows what cytoscape is.
+ */
+import type { NestingKind } from './nesting.js';
+/**
+ * A view names which relationships nest, in precedence order (ADR 0101). The
+ * short names a projection is authored in resolve to the kind identities the
+ * graph carries, in one place, so the schema's vocabulary and the canvas's
+ * cannot drift.
+ */
+export declare const NESTING_KIND_IDS: Readonly<Record<NestingKind, string>>;
+/**
+ * Whether a view draws pattern instances folded by default (#473).
+ *
+ * Lives here rather than in `projection.ts` for the reason `nesting.ts` exists:
+ * the browser needs the VALUE, and `projection.ts` drags Ajv and the projection
+ * schema in behind it. `projection.ts` re-exports both.
+ */
+export type FoldMode = 'instances' | 'none';
+/**
+ * What a view folds when it does not say: nothing. Folding hides detail, and a
+ * view that hid detail without being asked would be a surprise its author never
+ * wrote down.
+ */
+export declare const DEFAULT_FOLD: FoldMode;
+/** One node, reduced to what containment needs to know about it. */
+export interface FoldNode {
+    readonly id: string;
+    /** The kind as authored, profile-qualified or not. Unused by the rules here. */
+    readonly kind: string;
+    /**
+     * The core-vocabulary kind this resolves to. Every rule below reads THIS and
+     * never `kind`: a profile's `mule-api-operation` is an `applicationService`
+     * and must be treated as one, and the label it happens to carry is not a
+     * fact about what it is.
+     */
+    readonly coreKind: string;
+}
+/** One relationship, reduced to what containment needs to know about it. */
+export interface FoldEdge {
+    readonly id: string;
+    readonly kind: string;
+    readonly from: string;
+    readonly to: string;
+}
+/** How a pattern's wiring relates a slot to the instance that declares it. */
+export type SlotWiring = 'owned' | 'context' | 'unwired';
+/** One bound slot, as {@link foldTree} needs it. */
+export interface FoldMembership {
+    readonly member: string;
+    readonly slot: string;
+    readonly instance: string;
+    readonly wiring?: SlotWiring;
+}
+export interface FoldInput {
+    readonly nodes: readonly FoldNode[];
+    readonly edges: readonly FoldEdge[];
+    readonly memberships: readonly FoldMembership[];
+    readonly nesting: readonly NestingKind[];
+}
+/**
+ * Two parents claiming one child at the same precedence. Returned rather than
+ * resolved: picking a winner would hide a real modelling anomaly behind a
+ * layout that looks deliberate. The caller renders the child unnested and says
+ * so, which is what composition alone already did.
+ */
+export interface NestingConflict {
+    readonly child: string;
+    readonly claims: readonly {
+        readonly edgeId: string;
+        readonly kind: string;
+        readonly from: string;
+    }[];
+}
+export interface FoldTree {
+    readonly parentOf: ReadonlyMap<string, string>;
+    readonly consumedEdgeIds: ReadonlySet<string>;
+    readonly conflicts: readonly NestingConflict[];
+    /** Ids left unnested because their parent chain loops. */
+    readonly cycleMembers: readonly string[];
+}
+/**
+ * The parent-of map a view's nesting kinds imply.
+ *
+ * The compiler's `YM501` rule rejects one pair declaring both composition and
+ * aggregation; it does not reject two different compositions naming one child,
+ * which a single-parent field cannot represent either, nor a composition chain
+ * that loops. Both are real modelling anomalies, surfaced here rather than
+ * silently resolved: affected subjects come back unnested and every edge naming
+ * them stays an ordinary line, so the conflicting claims remain visible.
+ */
+export declare function nestingTree(edges: readonly FoldEdge[], nesting: readonly NestingKind[], coreKindOf: (id: string) => string): FoldTree;
+/**
+ * The containment tree: what a view nests, plus what a pattern owns.
+ *
+ * A slot member joins the tree only when all three hold, and each condition is
+ * a different way of getting the answer wrong:
+ *
+ * - **Exclusive.** A subject bound into two instances has two owners, and a
+ *   single-parent tree would silently pick one. Shared subjects stay outside.
+ * - **`owned` or `unwired`, never `context`.** A context slot names something
+ *   the instance USES and does not contain — the upstream API it calls, the
+ *   plane it runs on. Folding those would swallow half the landscape into
+ *   whichever box happened to reference it.
+ * - **Not a ruling.** See {@link RULING_CORE_KINDS}.
+ *
+ * A view's own nesting wins where both apply: the view is the more specific
+ * statement, and a reader who wrote `nesting: [composition]` meant it.
+ */
+export declare function foldTree(input: FoldInput): FoldTree;
+/** An edge that stands for one or more relationships hidden inside a fold. */
+export interface LiftedEdge {
+    readonly id: string;
+    readonly kind: string;
+    readonly from: string;
+    readonly to: string;
+    readonly count: number;
+    readonly relationshipIds: readonly string[];
+}
+/** The id a lifted edge takes. Deterministic, so a re-render is stable. */
+export declare const liftedEdgeId: (from: string, to: string, kind: string) => string;
+/**
+ * What the canvas draws once some instances are folded.
+ *
+ * A folded instance KEEPS its own node — it is still a subject, still
+ * selectable, still the thing a question is about — and gains what it is
+ * standing in for. Its descendants leave the output, and every edge with an end
+ * inside it is lifted to the box.
+ *
+ * Lifted edges of one kind between one ordered pair merge into a single edge
+ * carrying `count` and the ids it stands for, so seven `serving` relationships
+ * between two applications draw as one line labelled ×7 rather than as seven
+ * lines the reader has to count. An edge whose ends fold into the SAME box
+ * vanishes: it is internal, and the box is the statement now.
+ */
+export declare function foldGraph<N extends {
+    readonly id: string;
+}, E extends {
+    readonly id: string;
+    readonly kind: string;
+    readonly from: string;
+    readonly to: string;
+}>(graph: {
+    readonly nodes: readonly N[];
+    readonly edges: readonly E[];
+}, tree: Pick<FoldTree, 'parentOf'>, folded: ReadonlySet<string>): {
+    readonly nodes: (N & {
+        readonly folded: boolean;
+        readonly insideIds: readonly string[];
+    })[];
+    readonly edges: (E | LiftedEdge)[];
+};