@pascal-app/core 1.0.4 → 1.0.6

package/dist/agent-operations/search-materials.js

@@ -1,4 +1,7 @@
-import { MATERIAL_CATALOG, } from '../material-library.js';
+import { getDynamicLibraryMaterials, MATERIAL_CATALOG, } from '../material-library.js';
+/** The most a group lists at a time: a search's best, a browse by name. */
+const SEARCH_RESULTS = 12;
+const BROWSE_RESULTS = 150;
 /**
  * Building words as the library writes them: a plan or a brief says timber, weatherboard, render
  * where the library says wood, siding, stucco.
@@ -53,6 +56,8 @@ function shadeOf(hex) {
     };
 }
 const stem = (word) => (word.length > 4 && word.endsWith('s') ? word.slice(0, -1) : word);
+/** A word that searches: three letters or more, or any word with a digit ("48" of a plank). */
+const searches = (word) => (word.length > 2 || /\d/.test(word)) && !STOP_WORDS.has(word);
 /** Words that tell no material from another: "white render for the walls" asks for three things. */
 const STOP_WORDS = new Set(['and', 'the', 'for', 'with', 'from', 'into', 'some', 'like', 'its']);
 const wordsOf = (text) => text
@@ -61,6 +66,8 @@ const wordsOf = (text) => text
     .filter(Boolean);
 /** Whether a material can go on a surface: one that names no surface goes anywhere (flat colours). */
 const suits = (material, surface) => !material.surfaces || material.surfaces.includes(surface);
+/** A material's id with its words run together, as a piece of it is asked ("plank48"). */
+const idRun = (material) => material.id.toLowerCase().replace(/[^a-z0-9]/g, '');
 /**
  * Whether a material answers a query word: by a word of its text (whole, or begun by a form of four
  * letters or more: tile answers tiles, for never answers forest), the trade vocabulary, shade or
@@ -71,6 +78,8 @@ function answers(material, text, word) {
     const said = (token, form) => token === form || stem(token) === form || (form.length >= 4 && token.startsWith(form));
     if (forms.some((form) => text.some((token) => said(token, form))))
         return true;
+    if ((word.length >= 4 || /\d/.test(word)) && idRun(material).includes(word))
+        return true;
     const shade = SHADES[word];
     const colour = shadeOf(material.previewColor);
     if (shade && colour && shade(colour))
@@ -79,33 +88,78 @@ function answers(material, text, word) {
     const surface = SURFACE_WORDS[word] ?? SURFACE_WORDS[stem(word)];
     return !!surface && !!material.surfaces?.includes(surface);
 }
-/** `search_materials`: the library's materials by words, best first, and the words none answers. */
-export const searchMaterials = (_nodes, { queries }) => ({
-    result: {
-        groups: queries.map(({ query, surface }) => {
-            const words = wordsOf(query).filter((word) => word.length > 2 && !STOP_WORDS.has(word));
-            const scored = MATERIAL_CATALOG.filter((material) => !surface || suits(material, surface)).map((material) => {
-                const text = wordsOf(`${material.id} ${material.label} ${material.category} ${material.description ?? ''}`);
-                return { material, hits: words.filter((word) => answers(material, text, word)) };
-            });
-            const missing = words.filter((word) => !scored.some(({ hits }) => hits.includes(word)));
-            const best = scored
-                .filter(({ hits }) => hits.length)
-                .sort((a, b) => b.hits.length - a.hits.length || a.material.label.localeCompare(b.material.label))
-                .slice(0, 12);
+/** Pascal's library, then what the host registered besides (a registration never shadows one). */
+function libraryMaterials() {
+    const pascal = new Set(MATERIAL_CATALOG.map((material) => material.id));
+    return [
+        ...MATERIAL_CATALOG,
+        ...getDynamicLibraryMaterials().filter((material) => !pascal.has(material.id)),
+    ];
+}
+const asResult = (material) => ({
+    ref: `library:${material.id}`,
+    label: material.label,
+    kind: material.category,
+    surfaces: material.surfaces ?? [],
+    ...(material.previewColor ? { color: material.previewColor } : {}),
+});
+const byName = (a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id);
+/** Colour options for a finish the library lacks: nearest library colour, or exact native. */
+const missingMaterialFacts = `paint with color gives the nearest library colour and says how far it moved (ΔE); a native material, paint with material: { properties: { color } }, keeps the exact colour.`;
+/**
+ * `search_materials`: the library's materials by words, best first, and the words none answers;
+ * without a query, a browse of a kind, a surface or the whole library. Either lists a page at a
+ * time, saying how many more there are and the offset that lists them.
+ */
+export const searchMaterials = (_nodes, { queries }) => {
+    const library = libraryMaterials();
+    const groups = queries.map(({ query = '', kind, surface, offset = 0 }) => {
+        const pool = library.filter((material) => (!kind || material.category === kind) && (!surface || suits(material, surface)));
+        const asked = {
+            ...(query ? { query } : {}),
+            ...(kind ? { kind } : {}),
+            ...(surface ? { surface } : {}),
+            ...(offset ? { offset } : {}),
+        };
+        const page = (listed, size) => {
+            const more = listed.length - offset - size;
             return {
-                query,
-                ...(surface ? { surface } : {}),
-                results: best.map(({ material }) => ({
-                    ref: `library:${material.id}`,
-                    label: material.label,
-                    kind: material.category,
-                    surfaces: material.surfaces ?? [],
-                    ...(material.previewColor ? { color: material.previewColor } : {}),
-                })),
-                ...(missing.length ? { missing } : {}),
+                results: listed.slice(offset, offset + size).map(asResult),
+                ...(more > 0 ? { more, next: offset + size } : {}),
             };
-        }),
-        message: 'Materials best first, as library:<id> refs for paint. The words no material answers are under missing: the library lacks them.',
-    },
-});
+        };
+        if (!query.trim())
+            return { ...asked, ...page([...pool].sort(byName), BROWSE_RESULTS) };
+        // A query of words too short or too common to tell materials apart finds nothing; it
+        // never browses the library in its place.
+        const said = wordsOf(query);
+        const words = said.filter(searches);
+        if (!words.length)
+            return { ...asked, results: [], missing: said };
+        const scored = pool.map((material) => {
+            const text = wordsOf(`${material.id} ${material.label} ${material.category} ${material.description ?? ''}`);
+            return { material, hits: words.filter((word) => answers(material, text, word)) };
+        });
+        // A three-letter piece nothing answers as a word ("cco" of stucco) is looked for in ids.
+        for (const word of words) {
+            if (word.length !== 3 || scored.some(({ hits }) => hits.includes(word)))
+                continue;
+            for (const entry of scored)
+                if (idRun(entry.material).includes(word))
+                    entry.hits.push(word);
+        }
+        const missing = words.filter((word) => !scored.some(({ hits }) => hits.includes(word)));
+        const best = scored
+            .filter(({ hits }) => hits.length)
+            .sort((a, b) => b.hits.length - a.hits.length || byName(a.material, b.material))
+            .map(({ material }) => material);
+        return { ...asked, ...page(best, SEARCH_RESULTS), ...(missing.length ? { missing } : {}) };
+    });
+    const lacking = groups.some((group) => 'missing' in group);
+    return {
+        result: {
+            groups,
+            message: `Materials as library:<id> refs for paint: a search best first, a browse by name. A long list says how many more there are (more) and the offset that lists them (next). The words no material answers are under missing: the library lacks them.${lacking ? ` ${missingMaterialFacts}` : ''}`,
+        },
+    };
+};

package/dist/agent-operations/set-checkpoint.d.ts

@@ -0,0 +1,9 @@
+import type { AgentOperation } from './types.js';
+/**
+ * `set_checkpoint`: the scene now, remembered under a name. The operation takes the checkpoint and
+ * hands it back for the host to keep with the session; nothing in the scene changes.
+ */
+export declare const setCheckpoint: AgentOperation<{
+    name: string;
+}>;
+//# sourceMappingURL=set-checkpoint.d.ts.map

package/dist/agent-operations/set-checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-checkpoint.d.ts","sourceRoot":"","sources":["../../src/agent-operations/set-checkpoint.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CA+B1D,CAAA"}

package/dist/agent-operations/set-checkpoint.js

@@ -0,0 +1,31 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { EMPTY_SESSION, MAX_CHECKPOINT_NODES, MAX_CHECKPOINTS, takeCheckpoint, } from './scene-checkpoint.js';
+/**
+ * `set_checkpoint`: the scene now, remembered under a name. The operation takes the checkpoint and
+ * hands it back for the host to keep with the session; nothing in the scene changes.
+ */
+export const setCheckpoint = (nodes, input, context) => {
+    const name = input.name.trim();
+    if (!name)
+        refuse('name_required', 'Give the checkpoint a name, e.g. "walls done".');
+    const session = context.session ?? EMPTY_SESSION;
+    const names = Object.keys(session.checkpoints);
+    const replaced = names.includes(name);
+    if (!replaced && names.length >= MAX_CHECKPOINTS)
+        refuse('too_many_checkpoints', `A session keeps at most ${MAX_CHECKPOINTS} checkpoints and has ${names.join(', ')}. Use one of those names to replace it.`, { checkpoints: names });
+    const size = Object.keys(nodes).length;
+    if (size > MAX_CHECKPOINT_NODES)
+        refuse('scene_too_large', `The scene has ${size} nodes; a checkpoint is kept for at most ${MAX_CHECKPOINT_NODES}.`, { nodes: size });
+    const checkpoint = takeCheckpoint(nodes, name, session.made.length);
+    return {
+        result: {
+            ok: true,
+            name,
+            replaced,
+            nodes: size,
+            checkpoints: replaced ? names : [...names, name],
+            message: `Checkpoint "${name}" kept with this session. verify_scene({ since: "${name}" }) lists what changes after it.`,
+        },
+        keep: { checkpoint },
+    };
+};

package/dist/agent-operations/set-ground-level.d.ts

@@ -0,0 +1,12 @@
+import type { AgentOperation } from './types.js';
+type SetGroundLevelInput = {
+    levelId: string;
+};
+/**
+ * `set_ground_level`: the level asked for becomes the building's ground floor — named on the
+ * building, its floor the top of the foundation over grade (as the building's region and style seat it), index 0 — the same change the level panel's "Set as ground floor"
+ * writes (`buildGroundLevelChanges`).
+ */
+export declare const setGroundLevel: AgentOperation<SetGroundLevelInput>;
+export {};
+//# sourceMappingURL=set-ground-level.d.ts.map

package/dist/agent-operations/set-ground-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-ground-level.d.ts","sourceRoot":"","sources":["../../src/agent-operations/set-ground-level.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C,KAAK,mBAAmB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,cAAc,CAAC,mBAAmB,CAuD9D,CAAA"}

package/dist/agent-operations/set-ground-level.js

@@ -0,0 +1,61 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { buildGroundLevelChanges } from '../building/ground-level.js';
+import { requireLevel } from './level-target.js';
+import { levelRole } from './scene-queries.js';
+/**
+ * `set_ground_level`: the level asked for becomes the building's ground floor — named on the
+ * building, its floor the top of the foundation over grade (as the building's region and style seat it), index 0 — the same change the level panel's "Set as ground floor"
+ * writes (`buildGroundLevelChanges`).
+ */
+export const setGroundLevel = (nodes, input) => {
+    const level = requireLevel(nodes, input.levelId);
+    const { role } = levelRole(nodes, level);
+    if (role !== 'occupied')
+        refuse('not_a_storey', `${level.name ?? level.id} (${level.id}) is a ${role === 'roof' ? 'roof' : 'support'} level, not a storey: it cannot stand at grade as the ground floor.`, { levelId: level.id, role });
+    const built = buildGroundLevelChanges({
+        nodes: nodes,
+        levelId: level.id,
+    });
+    if (!built)
+        refuse('no_building', `Level ${level.id} is not in a building, so it has no ground line.`, {
+            levelId: level.id,
+        });
+    const { seat, moveBy } = built;
+    const floorElevation = Math.round((seat.floorElevation + moveBy) * 1e6) / 1e6;
+    const name = level.name ?? level.id;
+    const { aboveGrade, foundation } = seat;
+    const construction = {
+        region: foundation.region,
+        construction: foundation.construction.id,
+        basis: foundation.basis,
+    };
+    const inches = Math.round(aboveGrade / 0.0254);
+    if (built.unchanged)
+        return {
+            result: {
+                ok: true,
+                unchanged: true,
+                levelId: level.id,
+                buildingId: built.buildingId,
+                floorElevation: seat.floorElevation,
+                aboveGrade,
+                foundation: construction,
+                message: `${name} is already the ground floor, its floor ${aboveGrade} m (${inches} in) over grade (${foundation.construction.label} foundation; ${foundation.basis}).`,
+            },
+        };
+    return {
+        result: {
+            ok: true,
+            levelId: level.id,
+            buildingId: built.buildingId,
+            floorElevation,
+            gradeElevation: seat.gradeElevation,
+            aboveGrade,
+            foundation: construction,
+            movedBuildingBy: moveBy,
+            renumbered: built.renumbered,
+            message: `${name} is the ground floor: its floor, the top of the foundation where the wood framing starts, stands ${aboveGrade} m (${inches} in) over grade (${floorElevation.toFixed(2)} m over grade ${seat.gradeElevation.toFixed(2)} m), as a ${foundation.construction.label} foundation seats it: ${foundation.construction.seatBasis}; ${foundation.basis}. The levels with a lower index are below grade${moveBy === 0 ? '' : `; the building moved ${moveBy.toFixed(2)} m in height, its plan where it was`}.`,
+        },
+        changes: { update: built.update },
+    };
+};

package/dist/agent-operations/site.d.ts

@@ -0,0 +1,21 @@
+import { type YardKey } from '../lib/site-placement.js';
+import type { AgentOperation } from './types.js';
+type SiteInput = {
+    building?: string;
+    site?: string;
+};
+type PlaceBuildingInput = {
+    building?: string;
+    outline?: number[][];
+    yards?: Partial<Record<YardKey, number>>;
+    rotationDeg?: number;
+};
+/**
+ * `get_site`: the site a building stands on, in its level coordinates; a lot no building stands
+ * on yet, in site coordinates.
+ */
+export declare const getSite: AgentOperation<SiteInput>;
+/** `place_building`: stand a building on its site by its pose, its walls untouched. */
+export declare const placeBuilding: AgentOperation<PlaceBuildingInput>;
+export {};
+//# sourceMappingURL=site.d.ts.map

package/dist/agent-operations/site.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site.d.ts","sourceRoot":"","sources":["../../src/agent-operations/site.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,OAAO,EACb,MAAM,uBAAuB,CAAA;AAI9B,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,SAAS,CAAA;AAEzD,KAAK,SAAS,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AACrD,KAAK,kBAAkB,GAAG;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,CAAA;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAID;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,SAAS,CA4B7C,CAAA;AA2CD,uFAAuF;AACvF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,kBAAkB,CAmD5D,CAAA"}

package/dist/agent-operations/site.js

@@ -0,0 +1,123 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { isSiteFlatwork } from '../lib/site-flatwork.js';
+import { describeSiteBrief, placeBuildingPose, roundedSiteBrief, siteBrief, } from '../lib/site-placement.js';
+import { targetBuilding } from './add-level.js';
+import { pointInPolygon } from './plan-geometry.js';
+const r2 = (n) => Math.round(n * 100) / 100 || 0;
+/**
+ * `get_site`: the site a building stands on, in its level coordinates; a lot no building stands
+ * on yet, in site coordinates.
+ */
+export const getSite = (nodes, input, context) => {
+    if (input.site) {
+        const site = nodes[input.site];
+        if (!site)
+            refuse('site_not_found', `Site not found: ${input.site}.`, { siteId: input.site });
+        if (site.type !== 'site')
+            refuse('not_a_site', `Node ${input.site} is a ${site.type}, not a site.`, {
+                siteId: input.site,
+                type: site.type,
+            });
+    }
+    const anyBuilding = Object.values(nodes).some((node) => node.type === 'building');
+    const building = input.building || (anyBuilding && !input.site)
+        ? targetBuilding(nodes, input.building, context)
+        : null;
+    // a site named alone is read for the building viewed when it stands there
+    const brief = siteBrief(nodes, building ? { buildingId: building.id } : { siteId: input.site, levelId: context.activeLevelId });
+    if (!brief)
+        refuse('no_site', 'The scene has no site with a lot: add_level starts one.');
+    if (input.site && brief.siteId !== input.site)
+        refuse('building_not_on_site', `${building?.id} stands on ${brief.siteId}, not on ${input.site}: name one or the other.`, { buildingId: building?.id, siteId: input.site });
+    return { result: { ...roundedSiteBrief(brief), summary: describeSiteBrief(brief) } };
+};
+function footprintFacts(footprint) {
+    const b = footprint.bounds;
+    return {
+        footprint: {
+            size: [r2(b.maxX - b.minX), r2(b.maxZ - b.minZ)],
+            bounds: { minX: r2(b.minX), minZ: r2(b.minZ), maxX: r2(b.maxX), maxZ: r2(b.maxZ) },
+            centre: [r2(footprint.centre[0]), r2(footprint.centre[1])],
+        },
+        yards: Object.fromEntries(Object.entries(footprint.yards).map(([key, m]) => [key, m == null ? null : r2(m)])),
+        fit: footprint.fit,
+        overhang: {
+            lotM: r2(footprint.overhang.lotM),
+            setbacksM: r2(footprint.overhang.setbacksM),
+            sides: footprint.overhang.sides,
+        },
+    };
+}
+/**
+ * What stands on the building's levels outside its footprint and moves with it: fences, paths and
+ * the floor items out of doors (a plant cannot be told from a patio chair, so all of them).
+ */
+function outdoorOnLevels(nodes, buildingId, rings) {
+    const building = nodes[buildingId];
+    const levels = new Set(building?.type === 'building' ? building.children : []);
+    const outside = (x, z) => !rings.some((ring) => pointInPolygon([x, z], ring));
+    const moved = [];
+    for (const node of Object.values(nodes)) {
+        if (!(node.parentId && levels.has(node.parentId)))
+            continue;
+        const flatwork = node.type === 'slab' && isSiteFlatwork(node);
+        const outdoorItem = node.type === 'item' && outside(node.position[0] ?? 0, node.position[2] ?? 0);
+        if (node.type === 'fence' || flatwork || outdoorItem)
+            moved.push({ id: node.id, type: node.type, ...(node.name ? { name: node.name } : {}) });
+    }
+    return moved;
+}
+/** `place_building`: stand a building on its site by its pose, its walls untouched. */
+export const placeBuilding = (nodes, input, context) => {
+    const building = targetBuilding(nodes, input.building, context);
+    const placed = placeBuildingPose(nodes, {
+        buildingId: building.id,
+        ...(input.outline
+            ? { outline: input.outline.map((p) => [p[0] ?? 0, p[1] ?? 0]) }
+            : {}),
+        ...(input.yards ? { yards: input.yards } : {}),
+        ...(input.rotationDeg === undefined ? {} : { rotationDeg: input.rotationDeg }),
+    });
+    if (!placed.ok)
+        refuse(placed.code, placed.message, { buildingId: building.id });
+    const facts = footprintFacts(placed.footprint);
+    const rotationDeg = Math.round(((placed.rotation[1] * 180) / Math.PI) * 10) / 10 || 0;
+    const [x, , z] = placed.position;
+    const movedWithIt = placed.moved
+        ? outdoorOnLevels(nodes, building.id, placed.footprint.rings)
+        : [];
+    const where = `${describeSiteBrief({ ...placed.brief, footprint: placed.footprint }).at(-1)}.`;
+    const message = [
+        placed.moved
+            ? `${building.name ?? 'The building'} now stands at site [${r2(x)}, ${r2(z)}], ${rotationDeg}°. Its walls keep their level coordinates; draw new ones in the same frame.`
+            : `${building.name ?? 'The building'} already stands there: nothing moved.`,
+        where,
+        placed.brief.placeholder
+            ? 'The lot is the new-project placeholder: say so, and ask for the address or the site plan.'
+            : '',
+        movedWithIt.length
+            ? `${movedWithIt.length} outdoor node(s) on its levels moved with it (fences, paths, plants, outdoor furniture): re-trace them to the lot.`
+            : '',
+    ].filter(Boolean);
+    return {
+        result: {
+            ok: true,
+            buildingId: building.id,
+            position: placed.position.map(r2),
+            rotationDeg,
+            moved: placed.moved,
+            ...facts,
+            ...(movedWithIt.length ? { movedWithIt: movedWithIt.slice(0, 24) } : {}),
+            message: message.join(' '),
+        },
+        ...(placed.moved
+            ? {
+                changes: {
+                    update: [
+                        { id: building.id, data: { position: placed.position, rotation: placed.rotation } },
+                    ],
+                },
+            }
+            : {}),
+    };
+};

package/dist/agent-operations/types.d.ts

@@ -1,22 +1,79 @@
-import type { AnyNode, AssetInput, Collection, SceneMaterial, SceneMaterialId } from '../schema/index.js';
+import type { ZodType } from 'zod';
+import type { DesignBrief } from '../agent-tools/design-brief.js';
+import type { AnyNode, AssetInput, Collection, CompiledGeometryScript, SceneMaterial, SceneMaterialId } from '../schema/index.js';
+import type { AssetViewFacts } from './asset-views.js';
+import type { SessionKeep, SessionRecord } from './scene-checkpoint.js';
 export type SceneNodes = Readonly<Record<string, AnyNode>>;
 /**
- * What a surface knows beyond the scene: the chat knows the floor a person is viewing; a host that
- * keeps checkpoints passes the one asked for, and verify_scene compares the scene with it. A host
- * with an item library passes it as `catalog` (the chat and the hosted MCP: the published library;
- * the standalone MCP: its built-in list), resolved before the call, as the operations are sync.
- * A host that can store scene materials with the nodes that use them passes the scene's
- * `materials`: paint then checks scene refs against them and keeps a native material as one.
+ * What a surface knows beyond the scene: the chat knows the floor a person is viewing; a host
+ * passes the agent's session so far (the moments it named, what it made), which verify_scene
+ * compares the scene with. A host with an item library passes it as `catalog` (the chat and the
+ * hosted MCP: the published library; the standalone MCP: its built-in list), resolved before the
+ * call, as the operations are sync. A host that can store scene materials with the nodes that use
+ * them passes the scene's `materials`: paint then checks scene refs against them and keeps a native
+ * material as one.
  */
 export type AgentContext = {
     activeLevelId: string | null;
+    /**
+     * The schema the host checks a stored node of a kind by, for each kind it checks: a host that
+     * validates its plugins' nodes at its own write boundary lends it, so verify_scene reports what
+     * the host refuses. For a kind it does not check (undefined), the kind's registered schema, else
+     * core's, else none: a kind no schema knows.
+     */
+    nodeSchema?: (kind: string) => ZodType | undefined;
     /** Opaque here: its measure is the measure module's (scene-measure), which reads it. */
     checkpoint?: {
         name: string;
         measure: unknown;
     };
+    /** The agent's session so far. The host keeps it where its sessions live; it is never scene data. */
+    session?: SessionRecord;
     catalog?: readonly AssetInput[];
+    /**
+     * What a host read about catalog items before the call, by item id (`assetViewNeeds` says
+     * which): their pictures for view_assets, the names of their paintable surfaces for it and for
+     * paint. A host that cannot read them leaves them out.
+     */
+    assetViews?: Readonly<Record<string, AssetViewFacts>>;
     materials?: Readonly<Record<SceneMaterialId, SceneMaterial>>;
+    /** Modules built by the host before run_batch, indexed by call position. */
+    batchObjects?: Readonly<Record<number, BatchedObject>>;
+    batchCall?: number;
+    /**
+     * The design brief in force on a host that gates furnishing on one: `null` while there is none
+     * (placing or making furnishings is refused, `furnishingRefusal`), the brief once written. A
+     * host that does not gate leaves it out.
+     */
+    designBrief?: DesignBrief | null;
+    /**
+     * The person's words of the turn, on a host that has a person (the chat): the source quote of a
+     * design brief is checked against it. A host with no person's message (MCP) leaves it out and the
+     * quote is not checked.
+     */
+    requestText?: string;
+};
+/** One add_object call of a batch, built by its host: the compiled module, or why it failed. */
+export type BatchedObject = {
+    compiled: CompiledGeometryScript;
+} | {
+    failure: {
+        code: string;
+        message: string;
+    };
+};
+/** A write's operations in order, as apply_patch and update_node carry them. */
+export type NodeWrite = {
+    op: 'create';
+    node: AnyNode;
+    parentId?: string;
+} | {
+    op: 'update';
+    id: string;
+    data: Record<string, unknown>;
+} | {
+    op: 'delete';
+    id: string;
 };
 /** Edits an operation asks for; each surface applies them its own way, in one undo step. */
 export type SceneChanges = {
@@ -37,6 +94,8 @@ export type SceneChanges = {
 };
 export type AgentOperationOutcome = {
     result: Record<string, unknown>;
+    /** What the operation asks the host to keep with the session: a checkpoint it took. */
+    keep?: SessionKeep;
     changes?: SceneChanges;
     /**
      * For an edit that depends on construction the host derives from `changes` (rooms re-derived

package/dist/agent-operations/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent-operations/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEhG,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAE1D;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,wFAAwF;IACxF,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IAC/C,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IAC/B,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC,CAAA;CAC7D,CAAA;AAED,4FAA4F;AAC5F,MAAM,MAAM,YAAY,GAAG;IACzB,sEAAsE;IACtE,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;IACpC,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC/C,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,EAAE,CAAA;IACjD,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC,CAAA;CAChD,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK;QACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC/B,OAAO,CAAC,EAAE,YAAY,CAAA;KACvB,CAAA;CACF,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,KAAK,IAAI,CAC1C,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,YAAY,KAClB,qBAAqB,CAAA;AAE1B,qGAAqG;AACrG,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent-operations/types.ts"],"names":[],"mappings":"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"}

package/dist/agent-operations/verify-scene.d.ts

@@ -1,10 +1,43 @@
 import { type OpenWallEnd } from '../lib/room-graph.js';
+import { type CeilingObjectObservation } from './ceiling-object-observations.js';
+import { type RoomFinding } from './room-findings.js';
 import type { AgentOperation, SceneNodes } from './types.js';
+import { type WallObjectObservation } from './wall-object-observations.js';
 /** A problem verify_scene found, typed so it can be counted and acted on. */
-export type SceneIssue = {
+export type SceneIssue = CeilingObjectObservation | WallObjectObservation | RoomFinding | {
     type: string;
     message: string;
     severity?: 'info';
+} | {
+    type: 'schema_invalid';
+    message: string;
+    nodeId: string;
+    path: string;
+} | {
+    type: 'schema_unknown_kind';
+    message: string;
+    severity: 'info';
+    kind: string;
+    count: number;
+    /** The first few of them. */
+    nodeIds: string[];
+} | {
+    type: 'site_hidden';
+    message: string;
+    severity: 'info';
+    nodeId: string;
+} | {
+    type: 'wall_covering_slab_contact';
+    message: string;
+    severity?: 'info';
+    wallId: string;
+    slabId: string;
+    levelId: string;
+    wallTop: number;
+    slabUnderside: number;
+    slabTop: number;
+    penetration: number;
+    coplanar: boolean;
 } | {
     type: 'wall_open_end';
     message: string;
@@ -41,10 +74,11 @@ export declare function registerSceneReport(report: SceneReport): void;
 /** Runs a check in every verify_scene from now on; registering a check again replaces it. */
 export declare function registerSceneCheck(check: SceneCheck): void;
 /**
- * `verify_scene`: a self-check after complex edits. Per-level content and roles, then every
- * practical problem found, typed: rooms missing floors or ceilings, roof levels misused, storeys
- * with no stair, openings off their wall, stairs off their slab, blocked doors, overlapping
- * furniture, nodes their schema rejects.
+ * `verify_scene`: a self-check after complex edits. Per-level content, roles and enclosed spaces,
+ * then every practical problem found, typed: spaces with no room, rooms the walls do not close or
+ * with no name, rooms missing floors or ceilings, roof levels misused, storeys with no stair,
+ * openings off their wall, stairs off their slab, blocked doors, overlapping furniture, and every
+ * field a node's schema rejects, by node and path; a kind no schema here knows, once per kind.
  */
 export declare const verifyScene: AgentOperation<VerifySceneInput | undefined>;
 //# sourceMappingURL=verify-scene.d.ts.map

package/dist/agent-operations/verify-scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-scene.d.ts","sourceRoot":"","sources":["../../src/agent-operations/verify-scene.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAmBxE,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzD,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD;IACE,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC,CAAA;IACvB,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAA;IAClD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAEL,yFAAyF;AACzF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEhE;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,gBAAgB,KAAK,UAAU,EAAE,CAAA;CAClE,CAAA;AAED,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAInC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA;AAI/F,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,QAItD;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,QAKnD;AAoID;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,cAAc,CAAC,gBAAgB,GAAG,SAAS,CAwRpE,CAAA"}
+{"version":3,"file":"verify-scene.d.ts","sourceRoot":"","sources":["../../src/agent-operations/verify-scene.ts"],"names":[],"mappings":"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"}