@dotbep/core 0.2.7 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotbep/core",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,9 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "files": [
+    "dist"
+  ],
   "publishConfig": {
     "access": "public"
   },

package/examples/01-participants.ts

@@ -1,127 +0,0 @@
-// run: node --experimental-strip-types examples/01-participants.ts  (from core/)
-//
-// Covers: Bep.create(), roles, teams, members.
-//
-// A BEP starts with its participants: who is involved, what role they play,
-// and which organization they belong to. This example builds that foundation.
-//
-// Roles describe functional responsibilities within the project (e.g. BIM Manager).
-// Teams represent the contracting organizations (e.g. the architecture firm).
-// Members are the individual people — each identified by email and assigned a role.
-//
-// The dependency chain is: Role ← Member ← Team. A member references a role;
-// a team references its members. Deleting in the wrong order is blocked by
-// referential integrity, as shown at the end of each section.
-
-import { writeFileSync } from 'node:fs'
-import { Bep } from '../dist/index.js'
-
-const bep = Bep.create({ name: 'Example Project', code: 'EXP' })
-
-// ─── Roles ────────────────────────────────────────────────────────────────────
-
-// Roles are the functional positions that appear in RACI matrices and workflow
-// diagrams. They are project-level, not tied to a specific person or team.
-// The id is auto-generated (UUID) — capture it from the result to use later.
-
-console.log('=== roles ===')
-
-const rolesAdded = bep.roles.add([
-  { name: 'BIM Manager',     color: '#E63946' },
-  { name: 'BIM Coordinator', color: '#4444FF' },
-])
-const roleManagerId = rolesAdded.succeeded[0].id
-const roleCoordId   = rolesAdded.succeeded[1].id
-console.log('add succeeded:', rolesAdded.succeeded.map(r => r.name))
-
-// update() is a sparse patch — only the fields included in the call are touched.
-// Sending { id, color } leaves name and every other field unchanged.
-const rolesUpdated = bep.roles.update([
-  { id: roleManagerId, color: '#C1121F' },
-  { id: 'ghost-uuid',  color: '#000000' },   // fails — id not found
-])
-console.log('update succeeded:', rolesUpdated.succeeded.map(r => r.id))
-console.log('update failed:   ', rolesUpdated.failed)
-
-// ─── Teams ────────────────────────────────────────────────────────────────────
-
-// Teams represent the contracting parties defined in the appointment documents.
-// Their id is a short readable code (e.g. 'ARC') that appears in deliverable
-// naming codes, so it must be chosen carefully — it is not auto-generated.
-// isoRole maps to the ISO 19650 appointment roles (lead-appointed-party, etc.).
-
-console.log('\n=== teams ===')
-
-const teamsAdded = bep.teams.add([
-  { id: 'ARC', name: 'Architecture', isoRole: 'lead-appointed-party' },
-  { id: 'STR', name: 'Structure',    isoRole: 'appointed-party'      },
-  { id: 'ARC', name: 'Duplicate',    isoRole: 'appointed-party'      },   // fails — duplicate id
-])
-console.log('add succeeded:', teamsAdded.succeeded.map(t => t.id))
-console.log('add failed:   ', teamsAdded.failed)
-
-bep.teams.update([{ id: 'ARC', name: 'Architecture (Lead)' }])
-
-// A team with no references can be freely removed.
-const strRemoved = bep.teams.remove(['STR', 'XXX'])
-console.log('remove STR succeeded:', strRemoved.succeeded)
-console.log('remove XXX failed:   ', strRemoved.failed)
-
-// project.clientId is set directly on bep.data — the client team is the
-// appointing party and is referenced at the project level.
-bep.data.project.clientId = 'ARC'
-
-// Once a team is the project client, removing it would leave project.clientId
-// pointing to a non-existent entity — integrity blocks the operation.
-console.log('\n--- integrity: team referenced as project.clientId cannot be removed ---')
-const arcBlocked = bep.teams.remove(['ARC'])
-console.log('remove ARC (blocked by project.clientId):', arcBlocked.failed)
-
-// ─── Members ──────────────────────────────────────────────────────────────────
-
-// Members are the individual people who author and approve the BEP.
-// Email is the natural key — it must be unique across the entire BEP.
-// Each member is assigned exactly one role; the role must already exist.
-
-console.log('\n=== members ===')
-
-const membersAdded = bep.members.add([
-  { email: 'alice@arc.com', name: 'Alice Mora',  roleId: roleManagerId },
-  { email: 'bob@arc.com',   name: 'Bob Rivas',   roleId: roleCoordId   },
-  { email: 'alice@arc.com', name: 'Duplicate',   roleId: roleManagerId }, // fails — duplicate email
-  { email: 'ghost@x.com',   name: 'Ghost',       roleId: 'bad-role'    }, // fails — role not found
-])
-console.log('add succeeded:', membersAdded.succeeded.map(m => m.email))
-console.log('add failed:   ', membersAdded.failed)
-
-bep.members.update([
-  { email: 'alice@arc.com', name: 'Alice Mora (BIM Manager)' },
-  { email: 'nobody@x.com',  name: 'Ghost' },   // fails — email not found
-])
-
-// Teams are linked to their members via memberEmails. The representative is
-// the single point of contact for the team — also referenced by email.
-bep.teams.update([{
-  id:                  'ARC',
-  memberEmails:        ['alice@arc.com', 'bob@arc.com'],
-  representativeEmail: 'alice@arc.com',
-}])
-
-// A member referenced by a team's memberEmails cannot be removed — doing so
-// would silently orphan the team's roster.
-console.log('\n--- integrity: member referenced by team cannot be removed ---')
-const aliceBlocked = bep.members.remove(['alice@arc.com'])
-console.log('remove alice (blocked by team.memberEmails):', aliceBlocked.failed)
-
-// Similarly, a role referenced by any member cannot be removed — the member
-// would be left without a valid functional role in the BEP.
-console.log('\n--- integrity: role referenced by member cannot be removed ---')
-const roleBlocked = bep.roles.remove([roleManagerId])
-console.log('remove BIM Manager (blocked by alice.roleId):', roleBlocked.failed)
-
-// ─── Save ─────────────────────────────────────────────────────────────────────
-
-// save() returns a Buffer — the .bep zip in memory. Writing it to disk is the
-// caller's responsibility; the core has no filesystem dependency.
-writeFileSync('examples/example.bep', await bep.save())
-console.log('\nSaved → examples/example.bep')

package/examples/02-files.ts

@@ -1,100 +0,0 @@
-// part of: node --experimental-strip-types examples/run-all.ts  (use --02 to stop here)
-//
-// Covers: disciplines, extensions, assetTypes, softwares.
-//
-// These entities describe the file ecosystem of the project: what kinds of
-// documents are produced, in which formats, with which tools, and under which
-// discipline. They are referenced heavily by deliverables and LOIN entries.
-//
-// The dependency chain is:
-//   Extension ← AssetType ← Software
-//
-// Disciplines are orthogonal to that chain — they classify the authoring
-// responsibility (Architecture, Structure, MEP…) and appear in deliverable
-// naming codes and LOIN entries.
-
-import { readFileSync, writeFileSync } from 'node:fs'
-import { Bep } from '../dist/index.js'
-
-const bep = await Bep.open(readFileSync('examples/example.bep'))
-
-// ─── Disciplines ──────────────────────────────────────────────────────────────
-
-// Disciplines identify the engineering domain responsible for a set of
-// deliverables. Their id is a short readable code (e.g. 'ARQ') that appears
-// directly in naming codes — choose it to match the project convention.
-
-console.log('=== disciplines ===')
-
-bep.disciplines.add([
-  { id: 'ARQ', name: 'Architecture' },
-  { id: 'EST', name: 'Structure'    },
-  { id: 'MEP', name: 'MEP'          },
-  { id: 'ARQ', name: 'Duplicate'    },   // fails — duplicate id
-])
-console.log('list:', bep.disciplines.list().map(d => d.id))
-
-// associate ARC with ARQ to set up an integrity constraint
-bep.teams.update([{ id: 'ARC', disciplineIds: ['ARQ'] }])
-
-console.log('\n--- integrity: discipline referenced by team.disciplineIds cannot be removed ---')
-const discBlocked = bep.disciplines.remove(['ARQ'])
-console.log('remove ARQ (blocked by ARC.disciplineIds):', discBlocked.failed)
-
-// ─── Extensions ───────────────────────────────────────────────────────────────
-
-// Extensions are the file formats produced by the project (ifc, rvt, pdf…).
-// Their id is a lowercase file extension that appears in deliverable naming.
-// They are the base of the file type chain: Extension ← AssetType ← Software.
-
-console.log('\n=== extensions ===')
-
-bep.extensions.add([
-  { id: 'ifc', name: 'IFC'   },
-  { id: 'rvt', name: 'Revit' },
-  { id: 'pdf', name: 'PDF'   },
-])
-console.log('list:', bep.extensions.list().map(e => e.id))
-
-// ─── AssetTypes ───────────────────────────────────────────────────────────────
-
-// Asset types classify what a file represents (3D Model, Report, Drawing…).
-// Each type declares which extensions it can be delivered in. A deliverable then
-// references an asset type and optionally overrides the extension subset.
-
-console.log('\n=== assetTypes ===')
-
-bep.assetTypes.add([
-  { id: 'M3D', name: '3D Model', extensionIds: ['ifc', 'rvt'] },
-  { id: 'RPT', name: 'Report',   extensionIds: ['pdf']        },
-  { id: 'BAD', name: 'Bad Ext',  extensionIds: ['ghost']      },   // fails — extension not found
-])
-console.log('list:', bep.assetTypes.list().map(d => d.id))
-
-console.log('\n--- integrity: extension referenced by assetType cannot be removed ---')
-const extBlocked = bep.extensions.remove(['ifc'])
-console.log('remove ifc (blocked by M3D.extensionIds):', extBlocked.failed)
-
-// ─── Softwares ────────────────────────────────────────────────────────────────
-
-// Softwares are the authoring tools used on the project. Each one is linked to
-// the asset types it can produce. BIM Uses reference softwares to specify
-// which tools are required for a particular use case.
-
-console.log('\n=== softwares ===')
-
-bep.softwares.add([
-  { id: 'RVT', name: 'Revit',   version: '2025', assetTypeIds: ['M3D'] },
-  { id: 'ACR', name: 'Acrobat', version: '2024', assetTypeIds: ['RPT'] },
-  { id: 'BAD', name: 'Bad',     version: '1.0',  assetTypeIds: ['ghost'] }, // fails — assetType not found
-])
-console.log('list:', bep.softwares.list().map(s => s.id))
-
-console.log('\n--- integrity: assetType referenced by software cannot be removed ---')
-const dtBlocked = bep.assetTypes.remove(['M3D'])
-console.log('remove M3D (blocked by RVT.assetTypeIds):', dtBlocked.failed)
-
-// ─── Save ─────────────────────────────────────────────────────────────────────
-
-writeFileSync('examples/example.bep', await bep.save())
-console.log('\nSaved → examples/example.bep')

package/examples/03-workflows.ts

@@ -1,149 +0,0 @@
-// part of: node --experimental-strip-types examples/run-all.ts  (use --03 to stop here)
-//
-// Covers: actions, annexes, guides, workflows.
-//
-// Workflows are the heart of the BEP's process section. They describe how
-// information is produced and reviewed — who does what, in what order, and
-// under which RACI responsibility.
-//
-// The supporting entities build up toward the workflow:
-//   Action  — an atomic step (e.g. "Update model")
-//   Annex   — an external resource (video, document) that explains how to do it
-//   Guide   — a named collection of annexes, attached to a workflow as reference material
-//   Workflow — the full process diagram: a FlowDiagram with nodes and edges
-//
-// The diagram is stored as structured JSON (FlowDiagram), not Mermaid.
-// Mermaid is generated at runtime in the frontend via flowDiagramToMermaid().
-// Nodes reference actions and assign RACI roles to the people responsible.
-// Edges from process nodes must carry a triggerEventId — the event that causes
-// the transition.
-
-import { readFileSync, writeFileSync } from 'node:fs'
-import { Bep } from '../dist/index.js'
-
-const bep = await Bep.open(readFileSync('examples/example.bep'))
-
-// UUIDs are not stable across runs — look them up by name each time.
-const roleManagerId = bep.roles.list().find(r => r.name === 'BIM Manager')!.id
-
-// ─── Actions ──────────────────────────────────────────────────────────────────
-
-console.log('=== actions ===')
-
-const actionsAdded = bep.actions.add([
-  { name: 'Update model'                                    },
-  { name: 'Register issues', description: 'Log in BCF'     },
-  { name: 'Review model'                                    },
-])
-const actionUpdateId = actionsAdded.succeeded[0].id
-const actionIssuesId = actionsAdded.succeeded[1].id
-const actionReviewId = actionsAdded.succeeded[2].id
-console.log('add succeeded:', actionsAdded.succeeded.map(a => a.name))
-
-// ─── Events ───────────────────────────────────────────────────────────────────
-
-bep.events.add([
-  { id: 'done', name: 'Done' },
-])
-
-// ─── Annexes ──────────────────────────────────────────────────────────────────
-
-console.log('\n=== annexes ===')
-
-const annexesAdded = bep.annexes.add([
-  { name: 'IFC Tutorial', type: 'video',    url: 'https://example.com/ifc' },
-  { name: 'BIM Guide',    type: 'document', url: 'guides/bim-guide.pdf'    },
-])
-const anx1Id = annexesAdded.succeeded[0].id
-const anx2Id = annexesAdded.succeeded[1].id
-console.log('add succeeded:', annexesAdded.succeeded.map(a => a.name))
-
-// ─── Guides ───────────────────────────────────────────────────────────────────
-
-console.log('\n=== guides ===')
-
-const guidesAdded = bep.guides.add([
-  { name: 'IFC Export Guide',  annexIds: [anx1Id, anx2Id] },
-  { name: 'Coordination Guide'                             },
-  { name: 'Bad Annex Ref',     annexIds: ['ghost']        },   // fails — annex not found
-])
-console.log('add succeeded:', guidesAdded.succeeded.map(g => g.name))
-console.log('add failed:   ', guidesAdded.failed)
-
-console.log('\n--- integrity: annex referenced by guide cannot be removed ---')
-const annexBlocked = bep.annexes.remove([anx1Id])
-console.log('remove IFC Tutorial (blocked by guide.annexIds):', annexBlocked.failed)
-
-// ─── Workflows ────────────────────────────────────────────────────────────────
-
-// A workflow is a named process diagram stored as a FlowDiagram — a record of
-// nodes and edges identified by stable string keys. Each node can be a start,
-// end, process, or decision step. Process nodes reference an action and carry
-// RACI role assignments (responsible, accountable, consulted, informed).
-//
-// Edges outgoing from process nodes must declare a triggerEventId — the event
-// that causes the transition.
-//
-// All references inside the diagram — actionIds, roleIds, edge targets —
-// are validated on add and on update. Any broken reference fails the whole item.
-
-console.log('\n=== workflows ===')
-
-const wfAdded = bep.workflows.add([
-  {
-    name:        'Model Coordination',
-    description: 'Weekly model coordination workflow',
-    diagram: {
-      direction: 'LR',
-      nodes: {
-        start:  { type: 'start' },
-        update: { type: 'process', actionId: actionUpdateId, responsibleRoleIds: [roleManagerId] },
-        review: { type: 'process', actionId: actionReviewId, responsibleRoleIds: [roleManagerId], accountableRoleIds: [roleManagerId] },
-        issues: { type: 'process', actionId: actionIssuesId, responsibleRoleIds: [roleManagerId], consultedRoleIds:   [roleManagerId] },
-        end:    { type: 'end' },
-      },
-      edges: {
-        e1: { from: 'start',  to: 'update' },
-        e2: { from: 'update', to: 'review',  triggerEventId: 'done' },
-        e3: { from: 'review', to: 'issues',  triggerEventId: 'done' },
-        e4: { from: 'issues', to: 'end',     triggerEventId: 'done' },
-      },
-    },
-  },
-  // integrity failures on add —
-  {
-    name: 'Bad Action Ref',
-    diagram: { direction: 'LR', nodes: { n1: { type: 'process', actionId: 'ghost-action' } }, edges: {} },
-  },                                                           // fails — action not found
-  {
-    name: 'Bad Role Ref',
-    diagram: { direction: 'LR', nodes: { n1: { type: 'process', responsibleRoleIds: ['GHOST'] } }, edges: {} },
-  },                                                           // fails — role not found
-  {
-    name: 'Bad Edge Ref',
-    diagram: { direction: 'LR', nodes: { n1: { type: 'start' } }, edges: { e1: { from: 'n1', to: 'ghost-node' } } },
-  },                                                           // fails — edge target not found
-])
-const wfCoordId = wfAdded.succeeded[0].id
-console.log('add succeeded:', wfAdded.succeeded.map(w => w.name))
-console.log('add failed:   ', wfAdded.failed)
-
-console.log('\n--- integrity: action referenced by workflow node cannot be removed ---')
-const actionBlocked = bep.actions.remove([actionUpdateId])
-console.log('remove "Update model" (blocked by workflow node):', actionBlocked.failed)
-
-console.log('\n--- integrity: role referenced by workflow RACI cannot be removed ---')
-const roleBlocked = bep.roles.remove([roleManagerId])
-console.log('remove BIM Manager (blocked by workflow RACI):', roleBlocked.failed)
-
-console.log('\n--- update: diagram refs are re-validated on patch ---')
-const wfPatchFailed = bep.workflows.update([{
-  id:      wfCoordId,
-  diagram: { direction: 'LR', nodes: { n1: { type: 'process', actionId: 'ghost-action' } }, edges: {} },
-}])
-console.log('update with ghost actionId failed:', wfPatchFailed.failed)
-
-// ─── Save ─────────────────────────────────────────────────────────────────────
-
-writeFileSync('examples/example.bep', await bep.save())
-console.log('\nSaved → examples/example.bep')

package/examples/04-bim-uses.ts

@@ -1,70 +0,0 @@
-// part of: node --experimental-strip-types examples/run-all.ts  (use --04 to stop here)
-//
-// Covers: objectives, bimUses.
-//
-// BIM Uses answer the question "why are we using BIM on this project?".
-// Each use case ties together the project objectives it serves, the phases
-// it applies to, and the workflows that describe how it is carried out in practice.
-//
-// Objectives are the measurable targets — they exist independently and can be
-// referenced by multiple BIM Uses. BIM Uses are the bridge between the strategic
-// layer (what we want to achieve) and the operational layer (how we do it).
-//
-// Software traceability is derived from the workflow chain:
-//   BIMUse → workflowIds → diagram.nodes → actionId → action.softwareIds
-
-import { readFileSync, writeFileSync } from 'node:fs'
-import { Bep } from '../dist/index.js'
-
-const bep = await Bep.open(readFileSync('examples/example.bep'))
-
-const wfCoordId = bep.workflows.list().find(w => w.name === 'Model Coordination')!.id
-
-// ─── Objectives ───────────────────────────────────────────────────────────────
-
-console.log('=== objectives ===')
-
-const objectivesAdded = bep.objectives.add([
-  { description: 'Reduce coordination errors by 30%'       },
-  { description: 'Achieve LOD 350 at construction phase'   },
-  { description: 'Reduce RFI count by 25% vs last project' },
-])
-const obj1Id = objectivesAdded.succeeded[0].id
-const obj2Id = objectivesAdded.succeeded[1].id
-console.log('add succeeded:', objectivesAdded.succeeded.map(o => o.description))
-
-bep.objectives.update([
-  { id: obj1Id, description: 'Reduce coordination errors by 30% using Revit clash detection' },
-  { id: 'ghost-obj', description: 'Ghost' },   // fails
-])
-
-// ─── BIM Uses ─────────────────────────────────────────────────────────────────
-
-console.log('\n=== bimUses ===')
-
-const bimUsesAdded = bep.bimUses.add([
-  {
-    name:         'Model Coordination',
-    objectiveIds: [obj1Id],
-    workflowIds:  [wfCoordId],
-  },
-  {
-    name:         'Design Authoring',
-    objectiveIds: [obj2Id],
-  },
-  // integrity failures —
-  { name: 'Bad Objective', objectiveIds: ['ghost-obj'] }, // fails — objective not found
-  { name: 'Bad Workflow',  workflowIds:  ['ghost-wf']  }, // fails — workflow not found
-])
-const buCoordId = bimUsesAdded.succeeded[0].id
-console.log('add succeeded:', bimUsesAdded.succeeded.map(b => b.name))
-console.log('add failed:   ', bimUsesAdded.failed)
-
-console.log('\n--- integrity: workflow referenced by bimUse cannot be removed ---')
-const wfBlocked = bep.workflows.remove([wfCoordId])
-console.log('remove workflow (blocked by bimUse.workflowIds):', wfBlocked.failed)
-
-// ─── Save ─────────────────────────────────────────────────────────────────────
-
-writeFileSync('examples/example.bep', await bep.save())
-console.log('\nSaved → examples/example.bep')

package/examples/05-standards.ts

@@ -1,60 +0,0 @@
-// part of: node --experimental-strip-types examples/run-all.ts  (use --05 to stop here)
-//
-// Covers: standards.
-//
-// Standards are the normative documents embedded inside the .bep zip — the
-// naming conventions, export guidelines, and BIM requirements that govern how
-// the project must be executed. Each standard is a markdown file stored at an
-// auto-generated path inside the zip.
-//
-// Unlike other entities, standards carry file content in addition to metadata.
-// The add() call takes content as a markdown string; the core writes it to the
-// zip and stores the path in the entity. getContent/setContent read and overwrite
-// that file. remove() also deletes the .md file from the zip.
-//
-// This dual nature — entity record + embedded file — is what makes standards
-// versionable: the history system snapshots the .md file alongside bep.json
-// whenever it changes between commits.
-
-import { readFileSync, writeFileSync } from 'node:fs'
-import { Bep } from '../dist/index.js'
-
-const bep = await Bep.open(readFileSync('examples/example.bep'))
-
-// ─── Standards ────────────────────────────────────────────────────────────────
-
-// add() auto-generates a UUID path for each standard and writes the markdown
-// content to the zip immediately. The returned entity carries contentPath so
-// callers can see where the file lives inside the archive.
-const stdAdded = bep.standards.add([
-  { name: 'Naming Convention', content: '# Naming Convention\nAll files must follow ISO 19650 naming.' },
-  { name: 'IFC Export Guide',  content: '# IFC Export Guide\nUse IFC4 Reference View profile.'        },
-  { name: 'BIM Requirements',  content: '# BIM Requirements\nMinimum LOD per phase defined below.'    },
-])
-const stdNamingId = stdAdded.succeeded[0].id
-const stdIfcId    = stdAdded.succeeded[1].id
-const stdBimId    = stdAdded.succeeded[2].id
-console.log('add succeeded:', stdAdded.succeeded.map(s => s.name))
-console.log('content paths:', stdAdded.succeeded.map(s => s.contentPath))  // uuid-based paths in zip
-
-// getContent — reads the .md file from inside the zip
-const namingContent = await bep.standards.getContent(stdNamingId)
-console.log('\ngetContent (first 45 chars):', namingContent.slice(0, 45))
-
-// setContent — overwrites the .md file in the zip; no append, caller owns the full string
-bep.standards.setContent(stdNamingId, '# Naming Convention v2\nRevised rules after client review.')
-const updated = await bep.standards.getContent(stdNamingId)
-console.log('after setContent (first 45 chars):', updated.slice(0, 45))
-
-// remove — also deletes the corresponding .md file from the zip
-const stdRemoved = bep.standards.remove([stdIfcId, 'ghost-std'])
-console.log('\nremove succeeded:', stdRemoved.succeeded)
-console.log('remove failed:   ', stdRemoved.failed)
-
-console.log('standards remaining:', bep.standards.list().map(s => s.name))
-// → ['Naming Convention', 'BIM Requirements']
-
-// ─── Save ─────────────────────────────────────────────────────────────────────
-
-writeFileSync('examples/example.bep', await bep.save())
-console.log('\nSaved → examples/example.bep')

package/examples/06-schedule.ts

@@ -1,124 +0,0 @@
-// part of: node --experimental-strip-types examples/run-all.ts  (use --06 to stop here)
-//
-// Covers: phases, milestones, lbsNodes.
-//
-// The schedule section defines when information must be delivered and where
-// in the project's spatial breakdown each deliverable belongs.
-//
-// Phases are the major stages of the project (Design, Construction, Handover).
-// Milestones are the information exchange events within those phases — each one
-// has a concrete date and is the target that deliverables and LOIN entries
-// are anchored to.
-//
-// The LBS (Location Breakdown Structure) is a spatial tree of zones and
-// locations. Deliverable naming codes are derived from it: a deliverable on
-// floor P01 (child of block BLK) gets zone=BLK, location=P01 in its code.
-
-import { readFileSync, writeFileSync } from 'node:fs'
-import { Bep } from '../dist/index.js'
-
-const bep = await Bep.open(readFileSync('examples/example.bep'))
-
-// ─── Phases ───────────────────────────────────────────────────────────────────
-
-// Phases are the top-level time containers. They have no dates of their own;
-// the dates belong to milestones. Phases exist to group milestones and to
-// derive the phase label for each deliverable at render time.
-
-console.log('=== phases ===')
-
-const phasesAdded = bep.phases.add([
-  { name: 'Design'       },
-  { name: 'Construction' },
-  { name: 'Handover'     },
-])
-const desId = phasesAdded.succeeded[0].id
-const conId = phasesAdded.succeeded[1].id
-const hanId = phasesAdded.succeeded[2].id
-console.log('add succeeded:', phasesAdded.succeeded.map(p => p.name))
-
-// ─── Milestones ───────────────────────────────────────────────────────────────
-
-// Milestones are the information exchange events defined by ISO 19650 — the
-// moments at which teams must deliver a specific set of files. Each milestone
-// has a concrete date (ISO 8601) and belongs to a phase.
-// Deliverables and LOIN entries reference milestones to declare when and at
-// what level of development something must be ready.
-
-console.log('\n=== milestones ===')
-
-const milestonesAdded = bep.milestones.add([
-  { name: 'Design Delivery',       date: '2026-06-30', phaseId: desId },
-  { name: 'Construction Delivery', date: '2027-03-31', phaseId: conId },
-  { name: 'Handover Package',      date: '2027-09-30', phaseId: hanId },
-  { name: 'Ghost Phase',           date: '2026-12-31', phaseId: 'ghost-phase' }, // fails — phase not found
-])
-const m1Id = milestonesAdded.succeeded[0].id
-const m2Id = milestonesAdded.succeeded[1].id
-console.log('add succeeded:', milestonesAdded.succeeded.map(m => m.name))
-console.log('add failed:   ', milestonesAdded.failed)
-
-console.log('\n--- integrity: phase referenced by milestone cannot be removed ---')
-const phaseBlocked = bep.phases.remove([desId])
-console.log('remove Design (blocked by milestone.phaseId):', phaseBlocked.failed)
-
-// ─── LBS Nodes ────────────────────────────────────────────────────────────────
-
-// The LBS (Location Breakdown Structure) is a spatial tree used to locate
-// deliverables within the project. Each node is either a zone (container) or a
-// location (leaf). The id is the naming code that appears in deliverable names.
-//
-// Build the tree bottom-up — leaves first — so that child references resolve
-// on add. The root is the last node added; it is identified by having no parent.
-//
-//   SIT (zone, root)
-//   ├─ BLK (zone)
-//   │  ├─ P01 (location)
-//   │  └─ P02 (location)
-//   └─ FAC (zone)
-
-bep.lbsNodes.add([
-  { id: 'P01', name: 'Floor 1', type: 'location' },
-  { id: 'P02', name: 'Floor 2', type: 'location' },
-  { id: 'FAC', name: 'Facade',  type: 'zone'     },
-])
-bep.lbsNodes.add([
-  { id: 'BLK', name: 'Block A', type: 'zone', lbsNodeIds: ['P01', 'P02'] },
-])
-const lbsRoot = bep.lbsNodes.add([
-  { id: 'SIT', name: 'Site', type: 'zone', lbsNodeIds: ['BLK', 'FAC'] },
-])
-console.log('add root:', lbsRoot.succeeded.map(n => n.id))
-console.log('tree:    ', bep.lbsNodes.list().map(n => `${n.id}(${n.type})`))
-
-// validateTree: whole-tree structural check (roots must be zones, no cycles)
-console.log('\nvalidateTree (valid tree):', bep.lbsNodes.validateTree())  // []
-
-// resolveCodes: returns { zoneCode, locationCode } for deliverable naming
-console.log('\n--- resolveCodes ---')
-console.log('absent:    ', bep.lbsNodes.resolveCodes(undefined))  // XXX/XXX — no LBS node provided
-console.log('root SIT: ', bep.lbsNodes.resolveCodes('SIT'))     // ZZZ/ZZZ — root has no zone parent
-console.log('zone BLK:', bep.lbsNodes.resolveCodes('BLK'))   // BLK/ZZZ
-console.log('loc  P01:  ', bep.lbsNodes.resolveCodes('P01'))      // BLK/P01
-
-// per-node validation errors caught on add
-console.log('\n--- add validation errors ---')
-const badRef = bep.lbsNodes.add([{ id: 'BAD', name: 'Bad', type: 'zone', lbsNodeIds: ['ghost'] }])
-console.log('missing child ref:', badRef.failed)
-
-const badChild = bep.lbsNodes.add([{ id: 'BAD2', name: 'Bad', type: 'location', lbsNodeIds: ['FAC'] }])
-console.log('location with zone child:', badChild.failed)
-
-// validateTree catches structural errors not checked per-node (e.g. orphan location as root)
-bep.lbsNodes.add([{ id: 'ORPHAN', name: 'Orphan', type: 'location' }])
-console.log('\nvalidateTree (orphan location as root):', bep.lbsNodes.validateTree())
-bep.lbsNodes.remove(['ORPHAN'])
-
-console.log('\n--- integrity: node referenced as child cannot be removed ---')
-const nodeBlocked = bep.lbsNodes.remove(['BLK'])
-console.log('remove BLK (blocked by SIT.lbsNodeIds):', nodeBlocked.failed)
-
-// ─── Save ─────────────────────────────────────────────────────────────────────
-
-writeFileSync('examples/example.bep', await bep.save())
-console.log('\nSaved → examples/example.bep')