@ifc-lite/ids-authoring 0.0.0-stage → 0.2.1

package/dist/headless/diff.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A minimal semantic diff of two IDS documents, for `ifc-lite ids diff`
+ * and the MCP `ids_diff` tool.
+ *
+ * Matching is the re-identification cascade (`reidentify`): specifications
+ * by identifier, then name + applicability signature, then similarity;
+ * facets within a matched specification the same way. Matched nodes keep
+ * one node id, so "changed" is "same node id, different content", and a
+ * renamed specification is a change, not a remove plus an add.
+ *
+ * This is the shell the CLI and MCP surfaces need now. The full engine of
+ * IDS-104 (field-level paths inside constraints, a plain-language
+ * changelog, three-way merge) supersedes it; when it lands, this module is
+ * deleted and the surfaces call that engine instead.
+ */
+import type { IDSDocument } from '@ifc-lite/ids';
+import { type ReidentifyReport } from '../match/reidentify.js';
+export type IdsDiffChange = 'added' | 'removed' | 'changed';
+export interface IdsDiffEntry {
+    change: IdsDiffChange;
+    node: 'info' | 'spec' | 'facet';
+    /** The specification's name (the new one when it was renamed). */
+    spec?: string;
+    /** XML path of the node: in the new document, or in the old one for `removed`. */
+    path: string;
+    /** For `changed`: the field that differs (`name`, `cardinality`, `facet`, `optionality`, …). */
+    field?: string;
+    before?: string;
+    after?: string;
+    /** One plain-language line. */
+    text: string;
+}
+export interface IdsDiff {
+    identical: boolean;
+    entries: IdsDiffEntry[];
+    /** How specifications and facets were paired. */
+    matching: ReidentifyReport;
+}
+/** Compare `before` with `after`. Pure; never throws on parsed input. */
+export declare function diffIds(before: IDSDocument, after: IDSDocument): IdsDiff;
+//# sourceMappingURL=diff.d.ts.map

package/dist/headless/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/headless/diff.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA+E,MAAM,eAAe,CAAC;AAE9H,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK3E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iDAAiD;IACjD,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAkFD,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAsCxE"}

package/dist/headless/diff.js

@@ -0,0 +1,116 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { reidentify } from '../match/reidentify.js';
+import { describeFacet } from '../render/describe.js';
+import { studioDocumentFromIds } from './read.js';
+import { lostPaths } from './write.js';
+const INFO_FIELDS = ['title', 'copyright', 'version', 'description', 'author', 'date', 'purpose', 'milestone'];
+function same(a, b) {
+    return lostPaths(a, b).length === 0 && lostPaths(b, a).length === 0;
+}
+function cardinality(spec) {
+    if (spec.maxOccurs === 0)
+        return 'prohibited';
+    return (spec.minOccurs ?? 0) > 0 ? 'required' : 'optional';
+}
+function specFields(spec) {
+    return {
+        name: spec.name,
+        identifier: spec.identifier,
+        description: spec.description,
+        instructions: spec.instructions,
+        ifcVersion: spec.ifcVersions.join(' '),
+        cardinality: cardinality(spec),
+    };
+}
+function slots(doc, specIndex, section) {
+    const spec = doc.ids.specifications[specIndex];
+    const nodes = doc.nodes.specs[specIndex];
+    const out = new Map();
+    if (section === 'applicability') {
+        spec.applicability.facets.forEach((facet, index) => out.set(nodes.applicability[index].id, { facet, index }));
+    }
+    else {
+        spec.requirements.forEach((requirement, index) => out.set(nodes.requirements[index].id, { facet: requirement.facet, requirement, index }));
+    }
+    return out;
+}
+function describe(slot, section) {
+    return describeFacet(slot.facet, section, (slot.requirement?.optionality ?? 'required'));
+}
+function diffFacets(a, ai, b, bi, out) {
+    const spec = b.ids.specifications[bi].name;
+    for (const section of ['applicability', 'requirements']) {
+        const before = slots(a, ai, section);
+        const after = slots(b, bi, section);
+        const label = section === 'applicability' ? 'applicability' : 'requirement';
+        for (const [id, slot] of after) {
+            const path = `specifications[${bi}].${section}[${slot.index}]`;
+            const old = before.get(id);
+            if (!old) {
+                out.push({ change: 'added', node: 'facet', spec, path, text: `${spec}: ${label} added: ${describe(slot, section)}` });
+                continue;
+            }
+            if (!same(old.facet, slot.facet)) {
+                const was = describe(old, section);
+                const now = describe(slot, section);
+                out.push({ change: 'changed', node: 'facet', spec, path, field: 'facet', before: was, after: now, text: `${spec}: ${label} changed: ${was} → ${now}` });
+            }
+            else if (old.requirement && slot.requirement && old.requirement.optionality !== slot.requirement.optionality) {
+                const [was, now] = [old.requirement.optionality, slot.requirement.optionality];
+                const what = describeFacet(slot.facet, section);
+                out.push({ change: 'changed', node: 'facet', spec, path, field: 'optionality', before: was, after: now, text: `${spec}: ${label} changed from ${was} to ${now}: ${what}` });
+            }
+            if (old.requirement?.instructions !== slot.requirement?.instructions) {
+                out.push({ change: 'changed', node: 'facet', spec, path, field: 'instructions', before: old.requirement?.instructions, after: slot.requirement?.instructions, text: `${spec}: instructions of a requirement changed` });
+            }
+        }
+        for (const [id, slot] of before) {
+            if (after.has(id))
+                continue;
+            const path = `specifications[${ai}].${section}[${slot.index}]`;
+            out.push({ change: 'removed', node: 'facet', spec, path, text: `${spec}: ${label} removed: ${describe(slot, section)}` });
+        }
+    }
+}
+/** Compare `before` with `after`. Pure; never throws on parsed input. */
+export function diffIds(before, after) {
+    const a = studioDocumentFromIds(before);
+    const { doc: b, report } = reidentify(a, after);
+    const entries = [];
+    for (const field of INFO_FIELDS) {
+        const [was, now] = [before.info[field], after.info[field]];
+        if (was !== now)
+            entries.push({ change: 'changed', node: 'info', path: `info.${field}`, field, before: was, after: now, text: `Document ${field} changed from "${was ?? ''}" to "${now ?? ''}"` });
+    }
+    const indexOfA = new Map(a.nodes.specs.map((s, i) => [s.id, i]));
+    b.nodes.specs.forEach((nodes, bi) => {
+        const spec = b.ids.specifications[bi];
+        const ai = indexOfA.get(nodes.id);
+        if (ai === undefined) {
+            entries.push({ change: 'added', node: 'spec', spec: spec.name, path: `specifications[${bi}]`, text: `Specification "${spec.name}" added` });
+            return;
+        }
+        const was = specFields(a.ids.specifications[ai]);
+        const now = specFields(spec);
+        for (const field of Object.keys(now)) {
+            if (was[field] === now[field])
+                continue;
+            entries.push({
+                change: 'changed', node: 'spec', spec: spec.name, path: `specifications[${bi}]`, field, before: was[field], after: now[field],
+                text: field === 'name' ? `Specification "${was.name}" renamed to "${now.name}"` : `${spec.name}: ${field} changed from "${was[field] ?? ''}" to "${now[field] ?? ''}"`,
+            });
+        }
+        diffFacets(a, ai, b, bi, entries);
+    });
+    const removed = new Set(report.specs.removed);
+    a.nodes.specs.forEach((nodes, ai) => {
+        if (!removed.has(nodes.id))
+            return;
+        const name = a.ids.specifications[ai].name;
+        entries.push({ change: 'removed', node: 'spec', spec: name, path: `specifications[${ai}]`, text: `Specification "${name}" removed` });
+    });
+    return { identical: entries.length === 0, entries, matching: report };
+}
+//# sourceMappingURL=diff.js.map

package/dist/headless/diff.js.map

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

package/dist/headless/node-path.d.ts

@@ -0,0 +1,10 @@
+import type { StudioDocument } from '../document/types.js';
+import type { Uuid } from '../uuid.js';
+/**
+ * A path a person can find in the XML, for node `id`:
+ * `specifications[2].requirements[1].baseName`. Headless output prints
+ * this next to (or instead of) the node UUID, which means nothing outside
+ * the Studio. `undefined` for an id the document does not hold.
+ */
+export declare function nodePath(doc: StudioDocument, id: Uuid): string | undefined;
+//# sourceMappingURL=node-path.d.ts.map

package/dist/headless/node-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-path.d.ts","sourceRoot":"","sources":["../../src/headless/node-path.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAS1E"}

package/dist/headless/node-path.js

@@ -0,0 +1,24 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { locateNode } from '../document/node-index.js';
+/**
+ * A path a person can find in the XML, for node `id`:
+ * `specifications[2].requirements[1].baseName`. Headless output prints
+ * this next to (or instead of) the node UUID, which means nothing outside
+ * the Studio. `undefined` for an id the document does not hold.
+ */
+export function nodePath(doc, id) {
+    const loc = locateNode(doc, id);
+    if (!loc)
+        return undefined;
+    if (loc.kind === 'document')
+        return 'info';
+    const spec = `specifications[${loc.specIndex}]`;
+    if (loc.kind === 'spec')
+        return spec;
+    const facet = loc.section === 'applicability' ? `${spec}.applicability[${loc.facetIndex}]` : `${spec}.requirements[${loc.facetIndex}]`;
+    // Field names carry the facet type (`property.baseName`); the path already has it.
+    return loc.kind === 'constraint' ? `${facet}.${loc.field.slice(loc.field.indexOf('.') + 1)}` : facet;
+}
+//# sourceMappingURL=node-path.js.map

package/dist/headless/node-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-path.js","sourceRoot":"","sources":["../../src/headless/node-path.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAE/D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAIvD;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAmB,EAAE,EAAQ;IACpD,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,MAAM,CAAC;IAC3C,MAAM,IAAI,GAAG,kBAAkB,GAAG,CAAC,SAAS,GAAG,CAAC;IAChD,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,KAAK,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,kBAAkB,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,iBAAiB,GAAG,CAAC,UAAU,GAAG,CAAC;IACvI,mFAAmF;IACnF,OAAO,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AACvG,CAAC"}

package/dist/headless/read.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reading IDS for headless callers (CLI, MCP, SDK, Flow).
+ *
+ * Headless callers are stateless: the same XML read twice must give the
+ * same node ids, or an agent that reads a document, then refers to a node
+ * id in its next tool call, addresses nothing. Node ids are therefore
+ * derived from the content fingerprint instead of minted from the clock.
+ */
+import { type IDSDocument } from '@ifc-lite/ids';
+import type { StudioDocument } from '../document/types.js';
+/** Wrap a parsed IDS with node ids that depend only on its content. */
+export declare function studioDocumentFromIds(ids: IDSDocument): StudioDocument;
+/**
+ * Parse IDS XML into a `StudioDocument` with deterministic node ids.
+ * Throws the parser's `IDSParseError` on malformed input.
+ */
+export declare function readStudioDocument(xml: string): StudioDocument;
+/**
+ * Accept a `StudioDocument` that crossed a process boundary (an MCP tool
+ * argument, a Flow port, a file). Throws an `Error` naming the first
+ * problem. This checks the shape and the node index only: content written
+ * into the JSON by hand never passed the grounding gate, which is why
+ * `writeStudioDocument` audits what it serialises.
+ */
+export declare function parseStudioDocument(value: unknown): StudioDocument;
+//# sourceMappingURL=read.d.ts.map

package/dist/headless/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/headless/read.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAG3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,cAAc,CAItE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAE9D;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAgClE"}

package/dist/headless/read.js

@@ -0,0 +1,78 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * Reading IDS for headless callers (CLI, MCP, SDK, Flow).
+ *
+ * Headless callers are stateless: the same XML read twice must give the
+ * same node ids, or an agent that reads a document, then refers to a node
+ * id in its next tool call, addresses nothing. Node ids are therefore
+ * derived from the content fingerprint instead of minted from the clock.
+ */
+import { parseIDS } from '@ifc-lite/ids';
+import { fromIdsDocument } from '../document/from-ids.js';
+import { verifyNodeIndex } from '../document/node-index.js';
+import { fingerprintIds } from '../sidecar/sidecar.js';
+import { deriveId, isUuid } from '../uuid.js';
+/** Wrap a parsed IDS with node ids that depend only on its content. */
+export function studioDocumentFromIds(ids) {
+    const seed = fingerprintIds(ids);
+    let n = 0;
+    return fromIdsDocument(ids, { newId: () => deriveId(seed, `node:${n++}`) });
+}
+/**
+ * Parse IDS XML into a `StudioDocument` with deterministic node ids.
+ * Throws the parser's `IDSParseError` on malformed input.
+ */
+export function readStudioDocument(xml) {
+    return studioDocumentFromIds(parseIDS(xml));
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Accept a `StudioDocument` that crossed a process boundary (an MCP tool
+ * argument, a Flow port, a file). Throws an `Error` naming the first
+ * problem. This checks the shape and the node index only: content written
+ * into the JSON by hand never passed the grounding gate, which is why
+ * `writeStudioDocument` audits what it serialises.
+ */
+export function parseStudioDocument(value) {
+    if (!isRecord(value))
+        throw new Error('a Studio document must be a JSON object');
+    if (value.schemaVersion !== 1)
+        throw new Error(`unsupported Studio document schemaVersion ${String(value.schemaVersion)}`);
+    if (!isUuid(value.docId))
+        throw new Error('docId must be a UUID');
+    const ids = value.ids;
+    if (!isRecord(ids) || !isRecord(ids.info) || !Array.isArray(ids.specifications)) {
+        throw new Error('ids must hold info and specifications');
+    }
+    const nodes = value.nodes;
+    if (!isRecord(nodes) || !isUuid(nodes.document) || !Array.isArray(nodes.specs)) {
+        throw new Error('nodes must hold the document id and one entry per specification');
+    }
+    if (!isRecord(value.meta))
+        throw new Error('meta must be an object');
+    for (const [i, spec] of ids.specifications.entries()) {
+        if (!isRecord(spec) || !isRecord(spec.applicability) || !Array.isArray(spec.applicability.facets) || !Array.isArray(spec.requirements)) {
+            throw new Error(`specification ${i} must hold applicability.facets and requirements`);
+        }
+        const facets = [...spec.applicability.facets, ...spec.requirements.map((r) => (isRecord(r) ? r.facet : r))];
+        if (!facets.every((f) => isRecord(f) && typeof f.type === 'string')) {
+            throw new Error(`specification ${i} holds a facet without a type`);
+        }
+    }
+    for (const [i, sn] of nodes.specs.entries()) {
+        if (!isRecord(sn) || !Array.isArray(sn.applicability) || !Array.isArray(sn.requirements)) {
+            throw new Error(`nodes.specs[${i}] must hold applicability and requirements`);
+        }
+    }
+    // The checks above establish every field `verifyNodeIndex` reads.
+    const doc = value;
+    const problems = verifyNodeIndex(doc);
+    if (problems.length > 0)
+        throw new Error(`inconsistent node index: ${problems[0]}`);
+    return doc;
+}
+//# sourceMappingURL=read.js.map

package/dist/headless/read.js.map

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

package/dist/headless/schema-lookup.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Grounding lookups over the gate's schema tables, for agents that author
+ * IDS (MCP `ids_schema_search` / `ids_schema_entity` / `ids_schema_pset`).
+ * An agent that looks a name up here and then uses it passes the gate,
+ * because both read the same tables.
+ */
+import type { IFCVersion } from '@ifc-lite/ids';
+import { type GateContext } from '../gate/context.js';
+export type SchemaKind = 'entity' | 'pset' | 'property' | 'dataType';
+export interface SchemaHit {
+    kind: SchemaKind;
+    value: string;
+    /** 0..1, higher is better. */
+    score: number;
+    reason?: string;
+}
+export interface SchemaSearchOptions {
+    /** Restrict to one kind (default: all). */
+    kind?: SchemaKind;
+    /** Schema version (default IFC4). */
+    version?: IFCVersion;
+    limit?: number;
+}
+/** Rank schema names close to `query`, best first. */
+export declare function searchSchema(ctx: GateContext, query: string, options?: SchemaSearchOptions): SchemaHit[];
+export interface EntityDescription {
+    name: string;
+    version: IFCVersion;
+    abstract: boolean;
+    /** Supertypes, nearest first. */
+    ancestors: string[];
+    predefinedTypes: string[];
+    attributes: string[];
+    /** Standard property and quantity sets applicable to the entity or a supertype. */
+    propertySets: string[];
+}
+/** The entity as the gate sees it, or `undefined` when the name is not an entity of `version`. */
+export declare function describeEntity(ctx: GateContext, name: string, version?: IFCVersion): EntityDescription | undefined;
+export interface PsetDescription {
+    name: string;
+    version: IFCVersion;
+    applicableEntities: string[];
+    properties: {
+        name: string;
+        kind: string;
+        dataType?: string;
+        enumeration?: string[];
+    }[];
+}
+/** The standard property or quantity set, or `undefined` when `version` has none of that name. */
+export declare function describePset(ctx: GateContext, name: string, version?: IFCVersion): PsetDescription | undefined;
+//# sourceMappingURL=schema-lookup.d.ts.map

package/dist/headless/schema-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-lookup.d.ts","sourceRoot":"","sources":["../../src/headless/schema-lookup.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAoB,KAAK,WAAW,EAAsB,MAAM,oBAAoB,CAAC;AAG5F,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAErE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,qCAAqC;IACrC,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAoBD,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,SAAS,EAAE,CAc5G;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mFAAmF;IACnF,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,UAAmB,GAAG,iBAAiB,GAAG,SAAS,CAmB1H;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,CAAC;IACpB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACzF;AAED,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,UAAmB,GAAG,eAAe,GAAG,SAAS,CActH"}

package/dist/headless/schema-lookup.js

@@ -0,0 +1,77 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { inheritanceChain } from '../gate/context.js';
+import { rankCandidates } from '../gate/rank.js';
+const MAX_SETS_IN_REASON = 3;
+function pools(t) {
+    return {
+        entity: t.entityNames,
+        pset: t.psetNames,
+        property: [...t.psetsByProperty.keys()],
+        dataType: [...t.dataTypes.values()].map((d) => d.name),
+    };
+}
+function propertyReason(t, name) {
+    const sets = t.psetsByProperty.get(name);
+    if (!sets?.length)
+        return undefined;
+    const more = sets.length > MAX_SETS_IN_REASON ? ` and ${sets.length - MAX_SETS_IN_REASON} more` : '';
+    return `in ${sets.slice(0, MAX_SETS_IN_REASON).join(', ')}${more}`;
+}
+/** Rank schema names close to `query`, best first. */
+export function searchSchema(ctx, query, options = {}) {
+    const t = ctx.tables[options.version ?? 'IFC4'];
+    const limit = options.limit ?? 10;
+    const all = pools(t);
+    const kinds = options.kind ? [options.kind] : ['entity', 'pset', 'property', 'dataType'];
+    const hits = [];
+    for (const kind of kinds) {
+        for (const c of rankCandidates(query, all[kind], { limit })) {
+            const reason = kind === 'property' ? propertyReason(t, c.value) : undefined;
+            hits.push(reason ? { kind, value: c.value, score: c.score, reason } : { kind, value: c.value, score: c.score });
+        }
+    }
+    hits.sort((a, b) => b.score - a.score || a.value.localeCompare(b.value));
+    return hits.slice(0, limit);
+}
+/** The entity as the gate sees it, or `undefined` when the name is not an entity of `version`. */
+export function describeEntity(ctx, name, version = 'IFC4') {
+    const t = ctx.tables[version];
+    const chain = inheritanceChain(t, name);
+    if (chain.length === 0)
+        return undefined;
+    const [self, ...ancestors] = chain;
+    const names = new Set(chain.map((e) => e.name.toUpperCase()));
+    const propertySets = [...t.psets.values()]
+        .filter((p) => p.applicableEntities.some((a) => names.has(a.toUpperCase())))
+        .map((p) => p.name)
+        .sort();
+    return {
+        name: self.name,
+        version,
+        abstract: self.abstract,
+        ancestors: ancestors.map((e) => e.name),
+        predefinedTypes: [...self.predefinedTypes],
+        attributes: [...self.attributes],
+        propertySets,
+    };
+}
+/** The standard property or quantity set, or `undefined` when `version` has none of that name. */
+export function describePset(ctx, name, version = 'IFC4') {
+    const pset = ctx.tables[version].psets.get(name);
+    if (!pset)
+        return undefined;
+    return {
+        name: pset.name,
+        version,
+        applicableEntities: [...pset.applicableEntities],
+        properties: pset.properties.map((p) => ({
+            name: p.name,
+            kind: p.kind,
+            ...(p.dataType ? { dataType: p.dataType } : {}),
+            ...(p.enumeration ? { enumeration: [...p.enumeration] } : {}),
+        })),
+    };
+}
+//# sourceMappingURL=schema-lookup.js.map

package/dist/headless/schema-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-lookup.js","sourceRoot":"","sources":["../../src/headless/schema-lookup.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAU/D,OAAO,EAAE,gBAAgB,EAAwC,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAoBjD,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B,SAAS,KAAK,CAAC,CAAgB;IAC7B,OAAO;QACL,MAAM,EAAE,CAAC,CAAC,WAAW;QACrB,IAAI,EAAE,CAAC,CAAC,SAAS;QACjB,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;QACvC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;KACvD,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,CAAgB,EAAE,IAAY;IACpD,MAAM,IAAI,GAAG,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,IAAI,EAAE,MAAM;QAAE,OAAO,SAAS,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,kBAAkB,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,MAAM,GAAG,kBAAkB,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IACrG,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC;AACrE,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,GAAgB,EAAE,KAAa,EAAE,UAA+B,EAAE;IAC7F,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;IAClC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACrB,MAAM,KAAK,GAAiB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IACvG,MAAM,IAAI,GAAgB,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;YAC5D,MAAM,MAAM,GAAG,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC5E,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QAClH,CAAC;IACH,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAC9B,CAAC;AAcD,kGAAkG;AAClG,MAAM,UAAU,cAAc,CAAC,GAAgB,EAAE,IAAY,EAAE,UAAsB,MAAM;IACzF,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,gBAAgB,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACxC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,CAAC,IAAI,EAAE,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC;IACnC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC9D,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;SACvC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;SAC3E,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,IAAI,EAAE,CAAC;IACV,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO;QACP,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACvC,eAAe,EAAE,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC;QAC1C,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;QAChC,YAAY;KACb,CAAC;AACJ,CAAC;AASD,kGAAkG;AAClG,MAAM,UAAU,YAAY,CAAC,GAAgB,EAAE,IAAY,EAAE,UAAsB,MAAM;IACvF,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO;QACP,kBAAkB,EAAE,CAAC,GAAG,IAAI,CAAC,kBAAkB,CAAC;QAChD,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9D,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/headless/write.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Writing and formatting IDS for headless callers, with a losslessness guard.
+ *
+ * The XML writer is injected (`IdsWriter`). The CLI, MCP and SDK pass the
+ * full IDS 1.0 writer, `writeIdsXml` from `@ifc-lite/ids` (ADR-005, P-01).
+ * Whatever the writer, a
+ * headless write never returns XML that reads back with less content than
+ * it was given: the output is parsed again and every value the input
+ * defines must survive. Anything that does not is reported as `lost`, so
+ * `ids fmt --write` cannot silently delete an author or a restriction.
+ */
+import { type IDSDocument } from '@ifc-lite/ids';
+import type { StudioDocument } from '../document/types.js';
+/** Serialise an IDS document as IDS 1.0 XML. May throw to refuse. */
+export type IdsWriter = (ids: IDSDocument) => string;
+export interface WriteFailure {
+    ok: false;
+    reason: 'parse' | 'refused' | 'lossy';
+    message: string;
+    /** For `lossy`: paths whose value did not survive the round trip. */
+    lost?: string[];
+}
+export type WriteOutcome = {
+    ok: true;
+    xml: string;
+} | WriteFailure;
+export type FormatOutcome = {
+    ok: true;
+    xml: string;
+    changed: boolean;
+} | WriteFailure;
+/**
+ * Paths where `source` defines a value that `written` does not reproduce.
+ * Values only `written` has (defaults a parser fills in) are not losses.
+ */
+export declare function lostPaths(source: unknown, written: unknown, path?: string, out?: string[]): string[];
+/** Write `ids` and prove the XML reads back with the same content. */
+export declare function writeIdsChecked(ids: IDSDocument, write: IdsWriter): WriteOutcome;
+/** Serialise a Studio document (its `ids` content; the sidecar travels separately). */
+export declare function writeStudioDocument(doc: StudioDocument, write: IdsWriter): WriteOutcome;
+/**
+ * Canonical formatting: parse, write, verify. `changed` compares the
+ * canonical XML with the input byte for byte (after CRLF → LF).
+ */
+export declare function formatIds(xml: string, write: IdsWriter): FormatOutcome;
+//# sourceMappingURL=write.d.ts.map

package/dist/headless/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/headless/write.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,qEAAqE;AACrE,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAAC;AAEpE,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,YAAY,CAAC;AAOvF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,SAAK,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAwBpG;AAMD,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,GAAG,YAAY,CAuBhF;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,GAAG,YAAY,CAEvF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,aAAa,CAUtE"}

package/dist/headless/write.js

@@ -0,0 +1,103 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * Writing and formatting IDS for headless callers, with a losslessness guard.
+ *
+ * The XML writer is injected (`IdsWriter`). The CLI, MCP and SDK pass the
+ * full IDS 1.0 writer, `writeIdsXml` from `@ifc-lite/ids` (ADR-005, P-01).
+ * Whatever the writer, a
+ * headless write never returns XML that reads back with less content than
+ * it was given: the output is parsed again and every value the input
+ * defines must survive. Anything that does not is reported as `lost`, so
+ * `ids fmt --write` cannot silently delete an author or a restriction.
+ */
+import { parseIDS } from '@ifc-lite/ids';
+/** Fields that record source spelling or node identity, not content. */
+function ignored(key) {
+    return key === 'id' || key.endsWith('Raw') || key.startsWith('raw');
+}
+/**
+ * Paths where `source` defines a value that `written` does not reproduce.
+ * Values only `written` has (defaults a parser fills in) are not losses.
+ */
+export function lostPaths(source, written, path = '', out = []) {
+    if (source === undefined || source === null)
+        return out;
+    if (Array.isArray(source)) {
+        if (!Array.isArray(written)) {
+            out.push(path || '(root)');
+            return out;
+        }
+        source.forEach((item, i) => lostPaths(item, written[i], `${path}[${i}]`, out));
+        return out;
+    }
+    if (typeof source === 'object') {
+        if (typeof written !== 'object' || written === null || Array.isArray(written)) {
+            out.push(path || '(root)');
+            return out;
+        }
+        const w = written;
+        for (const [key, value] of Object.entries(source)) {
+            if (ignored(key))
+                continue;
+            lostPaths(value, w[key], path ? `${path}.${key}` : key, out);
+        }
+        return out;
+    }
+    if (source !== written)
+        out.push(path || '(root)');
+    return out;
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Write `ids` and prove the XML reads back with the same content. */
+export function writeIdsChecked(ids, write) {
+    let xml;
+    try {
+        xml = write(ids);
+    }
+    catch (err) {
+        return { ok: false, reason: 'refused', message: message(err) };
+    }
+    let reread;
+    try {
+        reread = parseIDS(xml);
+    }
+    catch (err) {
+        return { ok: false, reason: 'refused', message: `the writer produced XML that does not parse: ${message(err)}` };
+    }
+    const lost = lostPaths(ids, reread);
+    if (lost.length > 0) {
+        return {
+            ok: false,
+            reason: 'lossy',
+            message: `the IDS writer cannot represent ${lost.length} value(s) without loss`,
+            lost,
+        };
+    }
+    return { ok: true, xml };
+}
+/** Serialise a Studio document (its `ids` content; the sidecar travels separately). */
+export function writeStudioDocument(doc, write) {
+    return writeIdsChecked(doc.ids, write);
+}
+/**
+ * Canonical formatting: parse, write, verify. `changed` compares the
+ * canonical XML with the input byte for byte (after CRLF → LF).
+ */
+export function formatIds(xml, write) {
+    let ids;
+    try {
+        ids = parseIDS(xml);
+    }
+    catch (err) {
+        return { ok: false, reason: 'parse', message: message(err) };
+    }
+    const out = writeIdsChecked(ids, write);
+    if (!out.ok)
+        return out;
+    return { ok: true, xml: out.xml, changed: xml.replace(/\r\n/g, '\n') !== out.xml };
+}
+//# sourceMappingURL=write.js.map