@beehexa/hexasync-template-model 2608.20.18 → 2608.20.32

package/dist/componentKey.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The identity a component's `id`/`key` field actually denotes — the ONE implementation of it.
+ *
+ * The merge engine strips a surrounding quote pair and any leading `!`, and treats the `!` as a
+ * REMOVAL directive rather than part of the name. Anything that reads component identity out of a
+ * parsed file has to agree with that, or the two disagree about what a project contains: the index
+ * read `String(raw)` verbatim and so reported `objects/!DROPME` as a component the project declares,
+ * and `objects/'Quoted'` as distinct from `objects/Quoted`. Exported so there is one answer and not
+ * two (NFR-1 — the editor invents no semantics the runtime lacks).
+ *
+ * ### Why it lives in `model` rather than in `compose`, where it was written
+ *
+ * AD-33 rule 6: a node ADDRESS is built from the normalised key, because `!CHECK_EXISTS_ITEMS` — the one corpus step
+ * key outside `[A-Za-z0-9_]` — would otherwise put a removal directive inside an address, and specifically inside
+ * the address of a node the composer deletes. `nodeAddress.ts` is in this package because an address serves the
+ * diagram, the provenance anchor and an MCP citation alike, and `model` declares no dependencies at all, so it
+ * could not reach `compose`. Moving the function down rather than copying it keeps "the ONE implementation" true;
+ * `compose` re-exports it, so every existing importer is unaffected.
+ *
+ * Returns `undefined` for an absent id, which is not the same as an empty one.
+ */
+export declare function normalizeComponentKey(raw: unknown): {
+    id: string;
+    removes: boolean;
+} | undefined;
+//# sourceMappingURL=componentKey.d.ts.map

package/dist/componentKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentKey.d.ts","sourceRoot":"","sources":["../src/componentKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,GACX;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAQ9C"}

package/dist/componentKey.js

@@ -0,0 +1,32 @@
+/**
+ * The identity a component's `id`/`key` field actually denotes — the ONE implementation of it.
+ *
+ * The merge engine strips a surrounding quote pair and any leading `!`, and treats the `!` as a
+ * REMOVAL directive rather than part of the name. Anything that reads component identity out of a
+ * parsed file has to agree with that, or the two disagree about what a project contains: the index
+ * read `String(raw)` verbatim and so reported `objects/!DROPME` as a component the project declares,
+ * and `objects/'Quoted'` as distinct from `objects/Quoted`. Exported so there is one answer and not
+ * two (NFR-1 — the editor invents no semantics the runtime lacks).
+ *
+ * ### Why it lives in `model` rather than in `compose`, where it was written
+ *
+ * AD-33 rule 6: a node ADDRESS is built from the normalised key, because `!CHECK_EXISTS_ITEMS` — the one corpus step
+ * key outside `[A-Za-z0-9_]` — would otherwise put a removal directive inside an address, and specifically inside
+ * the address of a node the composer deletes. `nodeAddress.ts` is in this package because an address serves the
+ * diagram, the provenance anchor and an MCP citation alike, and `model` declares no dependencies at all, so it
+ * could not reach `compose`. Moving the function down rather than copying it keeps "the ONE implementation" true;
+ * `compose` re-exports it, so every existing importer is unaffected.
+ *
+ * Returns `undefined` for an absent id, which is not the same as an empty one.
+ */
+export function normalizeComponentKey(raw) {
+    if (raw === null || raw === undefined)
+        return undefined;
+    // Coerce so a numeric id (`id: 100`) does not crash `.replace`.
+    const unquoted = String(raw).replace(/^['"]([^'"]+)['"]$/, '$1');
+    return {
+        id: unquoted.replace(/^!+/, ''),
+        removes: unquoted.startsWith('!'),
+    };
+}
+//# sourceMappingURL=componentKey.js.map

package/dist/componentKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentKey.js","sourceRoot":"","sources":["../src/componentKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAY;IAEZ,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxD,gEAAgE;IAChE,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC;IACjE,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QAC/B,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC;KAClC,CAAC;AACJ,CAAC"}

package/dist/connectorSupport.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The unsupported-connector wording — ONE source, six surfaces (FR-10, Story 2.5; AD-31).
+ *
+ * `unsupported-connector-policy.md` states the contract in the feature's own words: *"This file exists so that
+ * the diagnostic, the picker, the preview, the compose report, the MCP server and the generated AI instructions
+ * all quote the same words. Six surfaces, one source."* This module IS that source in code, so a surface cannot
+ * paraphrase it and drift.
+ *
+ * It lives in the zero-dependency model package deliberately: the CLI's rules, the CLI's report renderer and the
+ * VS Code extension all already depend on this package, and nothing else can reach all three.
+ *
+ * ### Why the catalog facts are parameters rather than baked in
+ *
+ * The message names the catalog version and the connector count, because — per the policy — *"when the catalog is
+ * behind, that is the tool's fault, not the author's."* Those two numbers change every time the catalog ships, so
+ * baking them in would mean the wording and the data drifting apart by construction.
+ */
+/** What a request needs, in the order the policy lists them. Numbered by the renderer, not here. */
+export declare const REQUEST_REQUIREMENTS: readonly string[];
+export declare const SUPPORT_EMAIL = "support@beehexa.com";
+export interface CatalogFacts {
+    readonly catalogVersion: string | number;
+    readonly connectorCount: number;
+}
+/**
+ * The full block — for `explain`, the compose report appendix, the preview banner and the AI instructions.
+ */
+export declare function unsupportedConnectorGuidance(facts: CatalogFacts): string;
+/**
+ * The short form — for a diagnostic message, a hover, a status-bar item, a one-line tool response.
+ *
+ * Deliberately NOT a truncation of the long form: a truncated instruction that stops before the sandbox is an
+ * instruction someone will follow incompletely.
+ */
+export declare const UNSUPPORTED_CONNECTOR_SHORT: string;
+/**
+ * The pre-filled request email (FR-10's *Copy request email*).
+ *
+ * Pre-fills what the tooling KNOWS — the identity found, and the system name when the author gave one — and
+ * leaves the documentation link and the sandbox for the author, because inventing either would be worse than an
+ * empty line. G-6 applies to a request email as much as to a connection: never invent an identity.
+ */
+export declare function unsupportedConnectorRequestEmail(input: {
+    readonly connectorId: string;
+    readonly systemName?: string;
+    readonly systemCode?: string;
+    readonly facts: CatalogFacts;
+}): {
+    readonly to: string;
+    readonly subject: string;
+    readonly body: string;
+};
+/**
+ * The shipped connector catalog, as the rules need to read it (Story 2.2).
+ *
+ * ⛔ INJECTED, NOT BUNDLED. The rules run in this repo; the catalog ships in
+ * `hexasync-templates-vscode-ext/assets/connectors/catalog.json`, which `prd/addendum.md` §2 decided
+ * deliberately — *"a data file under the extension's asset tree, so it inherits the existing bump gate for
+ * free"* — while rejecting a separate published data package as *"more version surface than 22 rows justify"*.
+ *
+ * So the SHAPE lives here and the DATA arrives through `ValidationContext.connectorCatalog`, which is the
+ * pattern that context already uses for `variables`, `projects`, `libraryVariables` and `overwrites`. The rule
+ * stays one implementation that the Problems panel and the compose report both run (NFR-1) — and that an MCP
+ * server will run unchanged when Epic 6 builds one, which is the point of the seam rather than a claim that it
+ * exists today (Epic 2 review: three comments asserted that surface as present);
+ * only the data is supplied.
+ *
+ * The consequence is real and must never be silent: a bare `hexasync compose` has no catalog, so the
+ * catalog-dependent checks cannot run. `catalogChecksSkipped` is how a run says so out loud.
+ */
+export interface CatalogEntry {
+    readonly key: string;
+    readonly name: string;
+    readonly generation: string;
+    readonly connectorId: string;
+    readonly systemId?: string;
+    readonly systemCode?: string;
+    readonly status?: string;
+    /**
+     * The connector's logo, as a bare name (`lightspeed`), a filename (`lazada.png`), a repository path or an
+     * absolute URL — the third link of FR-11's icon chain (Story 3.1).
+     *
+     * Added because it was missing: all 22 shipped rows carry one and no consumer could read it.
+     */
+    readonly icon?: string;
+    /** The SYSTEM in a developer's terms — prefilled into a generated connection (Story 3.4). */
+    readonly description?: string;
+    /** The catalog key of the row that replaces this one — Story 3.9 offers the migration by name. */
+    readonly supersededBy?: string;
+    /** The catalog key of the row this one replaces. The inverse of `supersededBy`. */
+    readonly supersedes?: string;
+    /** False when this row must not be offered as something to connect to. Absent means yes. */
+    readonly connectable?: boolean;
+    /** True for a real id that is never a third-party system — the self connector, PostgreSQL, Basic Auth. */
+    readonly internal?: boolean;
+    /**
+     * How the system authenticates — `oauth2-authcode`, `api-key`, `basic`, `custom-app`, `rpa`, `unknown`.
+     *
+     * Declared in `connector-catalog.schema.json` and carried by no shipped row yet. Added to this type in the
+     * Story 5.5 review: the extension's connection card was built to state it and the editor's catalog loader was
+     * silently dropping the field, so it could never arrive however many rows declared it.
+     */
+    readonly authKind?: string;
+}
+export interface ConnectorCatalog {
+    readonly catalogVersion: string | number;
+    /** Every Gateway V3 row shares this connector id, which is why identity is the PAIR (addendum §2). */
+    readonly universalConnectorId: string;
+    readonly connectors: readonly CatalogEntry[];
+}
+/** Said once, so six surfaces cannot each invent their own way of admitting it. */
+export declare const CATALOG_CHECKS_SKIPPED = "Connector-catalog checks were skipped: no catalog was supplied to this run.";
+export declare function catalogFactsOf(catalog: ConnectorCatalog): CatalogFacts;
+export declare function isUniversalConnector(catalog: ConnectorCatalog, connectorId: string): boolean;
+/** Every entry registered under a connector id. More than one only for the universal connector. */
+export declare function entriesForConnector(catalog: ConnectorCatalog, connectorId: string): readonly CatalogEntry[];
+/** The entry a `(connectorId, systemCode)` pair names — the identity addendum §2 insists on. */
+export declare function entryForPair(catalog: ConnectorCatalog, connectorId: string, systemCode: string | undefined): CatalogEntry | undefined;
+/** Any entry claiming this system code, whatever its connector — how a copy-paste is caught. */
+export declare function entriesForSystemCode(catalog: ConnectorCatalog, systemCode: string): readonly CatalogEntry[];
+/** Any entry claiming this system id. The other half of the pair a copy-paste breaks. */
+export declare function entriesForSystemId(catalog: ConnectorCatalog, systemId: string): readonly CatalogEntry[];
+//# sourceMappingURL=connectorSupport.d.ts.map

package/dist/connectorSupport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectorSupport.d.ts","sourceRoot":"","sources":["../src/connectorSupport.ts"],"names":[],"mappings":"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"}

package/dist/connectorSupport.js

@@ -0,0 +1,116 @@
+/**
+ * The unsupported-connector wording — ONE source, six surfaces (FR-10, Story 2.5; AD-31).
+ *
+ * `unsupported-connector-policy.md` states the contract in the feature's own words: *"This file exists so that
+ * the diagnostic, the picker, the preview, the compose report, the MCP server and the generated AI instructions
+ * all quote the same words. Six surfaces, one source."* This module IS that source in code, so a surface cannot
+ * paraphrase it and drift.
+ *
+ * It lives in the zero-dependency model package deliberately: the CLI's rules, the CLI's report renderer and the
+ * VS Code extension all already depend on this package, and nothing else can reach all three.
+ *
+ * ### Why the catalog facts are parameters rather than baked in
+ *
+ * The message names the catalog version and the connector count, because — per the policy — *"when the catalog is
+ * behind, that is the tool's fault, not the author's."* Those two numbers change every time the catalog ships, so
+ * baking them in would mean the wording and the data drifting apart by construction.
+ */
+/** What a request needs, in the order the policy lists them. Numbered by the renderer, not here. */
+export const REQUEST_REQUIREMENTS = [
+    '**The system** you want to connect to (product name, and the edition/plan if it matters)',
+    '**Website URL**',
+    '**API documentation** — a link, or an attachment if the docs are not public. It must be **up to date**',
+    '**A sandbox / test environment**, with credentials we can use',
+];
+export const SUPPORT_EMAIL = 'support@beehexa.com';
+/**
+ * The full block — for `explain`, the compose report appendix, the preview banner and the AI instructions.
+ */
+export function unsupportedConnectorGuidance(facts) {
+    const numbered = REQUEST_REQUIREMENTS.map((requirement, index) => `${index + 1}. ${requirement}`).join('\n');
+    return [
+        '**This connector is not supported.**',
+        '',
+        `HexaSync currently supports only the connectors in the shipped catalog (\`catalogVersion ${facts.catalogVersion}\`, ` +
+            `\`${facts.connectorCount}\` connectors). To have a new system implemented, email the HexaSync Team at ` +
+            `**${SUPPORT_EMAIL}** with:`,
+        '',
+        numbered,
+        '',
+        'The HexaSync Team will contact you to proceed with the request.',
+    ].join('\n');
+}
+/**
+ * The short form — for a diagnostic message, a hover, a status-bar item, a one-line tool response.
+ *
+ * Deliberately NOT a truncation of the long form: a truncated instruction that stops before the sandbox is an
+ * instruction someone will follow incompletely.
+ */
+export const UNSUPPORTED_CONNECTOR_SHORT = `Not supported. Request this connector: email **${SUPPORT_EMAIL}** with the system name, website URL, ` +
+    `up-to-date API docs, and a sandbox environment.`;
+/**
+ * The pre-filled request email (FR-10's *Copy request email*).
+ *
+ * Pre-fills what the tooling KNOWS — the identity found, and the system name when the author gave one — and
+ * leaves the documentation link and the sandbox for the author, because inventing either would be worse than an
+ * empty line. G-6 applies to a request email as much as to a connection: never invent an identity.
+ */
+export function unsupportedConnectorRequestEmail(input) {
+    const named = input.systemName?.trim() || '<the system you want to connect to>';
+    return {
+        to: SUPPORT_EMAIL,
+        subject: `HexaSync connector request: ${named}`,
+        body: [
+            'Hello HexaSync Team,',
+            '',
+            `I would like to request support for a connector that is not in the shipped catalog ` +
+                `(catalogVersion ${input.facts.catalogVersion}, ${input.facts.connectorCount} connectors).`,
+            '',
+            `1. System: ${named}`,
+            `2. Website URL: `,
+            `3. API documentation (must be up to date): `,
+            `4. Sandbox / test environment and credentials: `,
+            '',
+            'Details found in my template:',
+            `- connector id: ${input.connectorId}`,
+            ...(input.systemCode ? [`- system code: ${input.systemCode}`] : []),
+            '',
+            'Thank you.',
+        ].join('\n'),
+    };
+}
+/** Said once, so six surfaces cannot each invent their own way of admitting it. */
+export const CATALOG_CHECKS_SKIPPED = 'Connector-catalog checks were skipped: no catalog was supplied to this run.';
+/**
+ * Ids are compared LOWERCASED.
+ *
+ * addendum §2: *"Casing is not guaranteed across the places these values arrive from — the platform UI had to
+ * build a lowercased index of its own map for the same reason."*
+ */
+const fold = (value) => (value ?? '').trim().toLowerCase();
+export function catalogFactsOf(catalog) {
+    return {
+        catalogVersion: catalog.catalogVersion,
+        connectorCount: catalog.connectors.length,
+    };
+}
+export function isUniversalConnector(catalog, connectorId) {
+    return fold(connectorId) === fold(catalog.universalConnectorId);
+}
+/** Every entry registered under a connector id. More than one only for the universal connector. */
+export function entriesForConnector(catalog, connectorId) {
+    return catalog.connectors.filter((entry) => fold(entry.connectorId) === fold(connectorId));
+}
+/** The entry a `(connectorId, systemCode)` pair names — the identity addendum §2 insists on. */
+export function entryForPair(catalog, connectorId, systemCode) {
+    return entriesForConnector(catalog, connectorId).find((entry) => fold(entry.systemCode) === fold(systemCode));
+}
+/** Any entry claiming this system code, whatever its connector — how a copy-paste is caught. */
+export function entriesForSystemCode(catalog, systemCode) {
+    return catalog.connectors.filter((entry) => fold(entry.systemCode) === fold(systemCode));
+}
+/** Any entry claiming this system id. The other half of the pair a copy-paste breaks. */
+export function entriesForSystemId(catalog, systemId) {
+    return catalog.connectors.filter((entry) => fold(entry.systemId) === fold(systemId));
+}
+//# sourceMappingURL=connectorSupport.js.map

package/dist/connectorSupport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectorSupport.js","sourceRoot":"","sources":["../src/connectorSupport.ts"],"names":[],"mappings":"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"}

package/dist/contract.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The compose contract version (AD-13, Story 1.10).
+ *
+ * A single integer, deliberately independent of every package's semver. Semver answers "did the
+ * API change?"; this answers a different and more dangerous question — "would the same input
+ * compose to a different output?" A patch release that fixes a typo in a report heading changes
+ * the version of the package but not the meaning of a composition, and warning about that would
+ * train everyone to ignore the warning.
+ *
+ * BUMP THIS **ONLY** when merge, inheritance or substitution semantics change:
+ *   - the merge engine's later-wins / id-matching behaviour
+ *   - the resolver's generation, weight, index or dedupe ordering
+ *   - which files are admitted to the variable pool, or how the pool is assembled
+ *   - the shape or precedence of `!md[...]` include resolution
+ *
+ * Do NOT bump it for: report wording, new diagnostics, performance work, refactors that hold the
+ * byte-identical baseline, or anything the composed `output.yaml` cannot observe.
+ *
+ * `scripts/contract-version-guard.mjs` enforces the first list in CI: touch a semantics file
+ * without moving this integer and the build fails.
+ *
+ * History
+ *   1 — Phase 1. Established at the end of Epic 1, covering the merge engine, the two-phase
+ *       weighted resolver, and the Story 1.8 rule admitting a declared external's variables.yaml
+ *       to the pool.
+ *   2 — Epic 1 review fixes (2026-08-02). Three changes that a composed output CAN observe:
+ *       variable precedence across sibling projects at the same generation no longer depends on
+ *       which slot a value came from; `!md[...]` paths are resolved after a partial's
+ *       `replacements` rather than before; and include discovery no longer misses a path
+ *       containing `]` nor aborts on a reference the resolver would never resolve.
+ *   3 — A missing `!md[...]` target no longer aborts the compose (2026-08-20). It resolved to an
+ *       exception before, so the composed output did not exist at all; it now resolves to an EMPTY
+ *       string and the miss is reported through `MergeHooks.onMissingInclude`, which the validation
+ *       registry raises as `MDI-1` (high). A composed `output.yaml` can observe this directly — the
+ *       same project that produced nothing now produces a document with an empty description — which
+ *       is precisely the "shape or precedence of `!md[...]` include resolution" clause above, so it
+ *       is a bump rather than an ACK. Losing an entire project's output and report to one absent
+ *       Markdown file cost the author the very report that would have named the file.
+ */
+export declare const COMPOSE_CONTRACT_VERSION = 3;
+/** What a version mismatch means for a caller that found one. */
+export interface ContractComparison {
+    ours: number;
+    /** `undefined` when the workspace declared none — never fabricated from `ours`. */
+    theirs: number | undefined;
+    match: boolean;
+    /** Human-readable, naming BOTH versions — a warning that names only one is unactionable. */
+    message?: string;
+}
+/**
+ * Compare the contract version a consumer was built against with the workspace toolchain's.
+ *
+ * Returns a comparison rather than throwing, because a mismatch must NOT stop anyone working
+ * (AC 2). The editor keeps composing; it just says so, and stamps what it produced.
+ */
+export declare function compareComposeContract(ours: number, theirs: number | undefined | null): ContractComparison;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAChC,kBAAkB,CAoBpB"}

package/dist/contract.js

@@ -0,0 +1,68 @@
+/**
+ * The compose contract version (AD-13, Story 1.10).
+ *
+ * A single integer, deliberately independent of every package's semver. Semver answers "did the
+ * API change?"; this answers a different and more dangerous question — "would the same input
+ * compose to a different output?" A patch release that fixes a typo in a report heading changes
+ * the version of the package but not the meaning of a composition, and warning about that would
+ * train everyone to ignore the warning.
+ *
+ * BUMP THIS **ONLY** when merge, inheritance or substitution semantics change:
+ *   - the merge engine's later-wins / id-matching behaviour
+ *   - the resolver's generation, weight, index or dedupe ordering
+ *   - which files are admitted to the variable pool, or how the pool is assembled
+ *   - the shape or precedence of `!md[...]` include resolution
+ *
+ * Do NOT bump it for: report wording, new diagnostics, performance work, refactors that hold the
+ * byte-identical baseline, or anything the composed `output.yaml` cannot observe.
+ *
+ * `scripts/contract-version-guard.mjs` enforces the first list in CI: touch a semantics file
+ * without moving this integer and the build fails.
+ *
+ * History
+ *   1 — Phase 1. Established at the end of Epic 1, covering the merge engine, the two-phase
+ *       weighted resolver, and the Story 1.8 rule admitting a declared external's variables.yaml
+ *       to the pool.
+ *   2 — Epic 1 review fixes (2026-08-02). Three changes that a composed output CAN observe:
+ *       variable precedence across sibling projects at the same generation no longer depends on
+ *       which slot a value came from; `!md[...]` paths are resolved after a partial's
+ *       `replacements` rather than before; and include discovery no longer misses a path
+ *       containing `]` nor aborts on a reference the resolver would never resolve.
+ *   3 — A missing `!md[...]` target no longer aborts the compose (2026-08-20). It resolved to an
+ *       exception before, so the composed output did not exist at all; it now resolves to an EMPTY
+ *       string and the miss is reported through `MergeHooks.onMissingInclude`, which the validation
+ *       registry raises as `MDI-1` (high). A composed `output.yaml` can observe this directly — the
+ *       same project that produced nothing now produces a document with an empty description — which
+ *       is precisely the "shape or precedence of `!md[...]` include resolution" clause above, so it
+ *       is a bump rather than an ACK. Losing an entire project's output and report to one absent
+ *       Markdown file cost the author the very report that would have named the file.
+ */
+export const COMPOSE_CONTRACT_VERSION = 3;
+/**
+ * Compare the contract version a consumer was built against with the workspace toolchain's.
+ *
+ * Returns a comparison rather than throwing, because a mismatch must NOT stop anyone working
+ * (AC 2). The editor keeps composing; it just says so, and stamps what it produced.
+ */
+export function compareComposeContract(ours, theirs) {
+    // An unknown version is not a mismatch. An older toolchain that predates the contract cannot
+    // report one, and treating absence as disagreement would warn every user of it, every time.
+    if (theirs === undefined || theirs === null) {
+        // `theirs: undefined`, NOT `theirs: ours` (corrected 2026-08-02). Echoing `ours` back was
+        // convenient for the `match` check and a lie to every caller that reads the field — a
+        // display or an artefact stamp would report a version the workspace never declared.
+        return { ours, theirs: undefined, match: true };
+    }
+    if (ours === theirs)
+        return { ours, theirs, match: true };
+    return {
+        ours,
+        theirs,
+        match: false,
+        message: `Compose contract mismatch: this extension composes under contract v${ours}, but the ` +
+            `workspace toolchain uses v${theirs}. The editor and your CI can therefore disagree ` +
+            `about a composed profile without either being wrong. Align the pinned ` +
+            `@beehexa/* packages with the workspace's toolchain.`,
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAY1C;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAY,EACZ,MAAiC;IAEjC,6FAA6F;IAC7F,4FAA4F;IAC5F,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5C,0FAA0F;QAC1F,sFAAsF;QACtF,oFAAoF;QACpF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC1D,OAAO;QACL,IAAI;QACJ,MAAM;QACN,KAAK,EAAE,KAAK;QACZ,OAAO,EACL,sEAAsE,IAAI,YAAY;YACtF,6BAA6B,MAAM,kDAAkD;YACrF,wEAAwE;YACxE,qDAAqD;KACxD,CAAC;AACJ,CAAC"}

package/dist/flowRender.d.ts

@@ -0,0 +1,89 @@
+/** A node as a renderer needs to see it — neither flow package's shape, deliberately. */
+export interface RenderNode {
+    /** The AD-33 canonical address. Projected to a mermaid id here, never by the caller. */
+    readonly address: string;
+    /** What the box says. */
+    readonly label: string;
+    /** Draw it as a decision diamond. */
+    readonly decides?: boolean;
+    /** Draw it as a stadium — a terminal, an unresolved target. */
+    readonly terminal?: boolean;
+}
+export interface RenderEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly label?: string;
+}
+/** One subgraph. A flat chart passes a single group with no title. */
+export interface RenderGroup {
+    readonly key: string;
+    readonly title?: string;
+    readonly nodes: readonly RenderNode[];
+}
+export type FlowDirection = 'TD' | 'LR';
+export interface RenderOverlay {
+    /** Addresses a run walked through. */
+    readonly traversed?: readonly string[];
+    /** Addresses a run failed at. */
+    readonly errored?: readonly string[];
+    /**
+     * Supplied by the caller, not chosen here.
+     *
+     * dashboard's live values come from its theme; the extension's webview themes its own. A renderer that hardcoded a
+     * colour would be wrong in one of light or dark — which is exactly why the extension delegates to a stylesheet.
+     */
+    readonly colors?: {
+        readonly traversed?: string;
+        readonly errored?: string;
+    };
+}
+export interface RenderOptions {
+    readonly direction?: FlowDirection;
+    /** One chart with a subgraph per group, versus one flat chart. */
+    readonly multiStage?: boolean;
+    /** Run highlighting. An ARGUMENT, never state on the model (AD-29). */
+    readonly overlay?: RenderOverlay;
+    /**
+     * Emitted as `classDef`/`class` rather than a per-element style, for a consumer whose stylesheet owns the colour.
+     * Carries no colour of its own — see rule 3.
+     */
+    readonly shapeClasses?: readonly {
+        readonly name: string;
+        readonly declaration: string;
+        readonly addresses: readonly string[];
+    }[];
+    /**
+     * What an EMPTY flow says.
+     *
+     * `epic-4-ground-truth.md` records three different answers across the three implementations and that Story 4.8's AC
+     * — *"saying so rather than rendering an empty diagram"* — needs one chosen. The CLI's answer is adopted: a single
+     * node stating what is absent. The wording is the caller's, because only the caller knows whether "no steps" or "no
+     * pusher steps" is the true sentence.
+     */
+    readonly emptyLabel?: string;
+}
+/**
+ * A label, safe inside `["…"]`.
+ *
+ * ⚠️ Escaping lives HERE, and Story 4.2's review is why it is written down: the frontend port moved escaping out of
+ * the model layer without recording that it had moved, and **4 real labels carry a raw newline**
+ * (`ShoplinePublicApp.yaml`). A renderer that forgets breaks a real connector's diagram.
+ *
+ * The `&` replacement comes FIRST, or the entities the later rules produce would themselves be re-escaped.
+ */
+export declare function escapeLabel(value: string): string;
+/**
+ * The diagram.
+ *
+ * Deterministic for a given `(groups, edges, opts)`: every list is emitted in the order given, duplicates are
+ * collapsed by first appearance, and nothing consults the clock or the environment.
+ */
+export declare function renderMermaid(groups: readonly RenderGroup[], edges: readonly RenderEdge[], opts?: RenderOptions): string;
+/**
+ * A titled section with a fenced diagram, and nothing else (rule 3).
+ *
+ * What the composition report embeds and what an MCP resource serves — the same string, because two surfaces
+ * describing one flow disagreeing is the defect this epic exists to remove.
+ */
+export declare function renderMarkdown(title: string, groups: readonly RenderGroup[], edges: readonly RenderEdge[], opts?: RenderOptions): string;
+//# sourceMappingURL=flowRender.d.ts.map

package/dist/flowRender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowRender.d.ts","sourceRoot":"","sources":["../src/flowRender.ts"],"names":[],"mappings":"AA2CA,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,IAAI,CAAC;AAExC,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,iCAAiC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS;QAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;KACvC,EAAE,CAAC;IACJ;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAwBD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjD;AAsFD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,IAAI,GAAE,aAAkB,GACvB,MAAM,CAiIR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,IAAI,GAAE,aAAkB,GACvB,MAAM,CAiBR"}