@uwmd/core 1.3.0 → 1.6.0

package/dist/cascade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAA4B,MAAM,YAAY,CAAC;AAIpF,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,OAAO,CACL,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7C;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IACrF,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B;yDACqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAID,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,kFAAkF;IAClF,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA4ED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,YAAY,EACpB,GAAG,GAAE,cAAmB,GACvB,aAAa,CA8Ef;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE5E"}
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"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"}

package/dist/cascade.js

@@ -1,11 +1,52 @@
 // Fallback cascade resolver — Protocol §V.7
 //
-// Walks the seven cascade steps in order; first hit wins. The producer that
+// Walks the eight cascade steps in order (seven before RFC 0021 §5 added
+// `inherited_assumption` at protocol 1.5.0); first hit wins. The producer that
 // uses this stamps the resulting `_meta.source` with the cascade step that
 // produced the value. See FORMAT_SPEC §3.4 (provisional flag) and §2.6
 // (source tags).
 import { getAssetClassDefaults } from './defaults.js';
 import { deepGet } from './parser.js';
+/**
+ * Raised when two equidistant ancestors assert the same field. Diamond
+ * inheritance resolves explicitly or not at all — silently picking one would
+ * make the answer depend on graph traversal order, which is the class of bug
+ * this whole RFC is written to avoid.
+ */
+export class AmbiguousInheritanceError extends Error {
+    code = 'COMP-AMBIGUOUS-INHERIT';
+    field_path;
+    ancestors;
+    constructor(field_path, ancestors) {
+        super(`[COMP-AMBIGUOUS-INHERIT] Equidistant ancestors ${ancestors
+            .map((a) => `'${a}'`)
+            .join(' and ')} both assert '${field_path}'. Resolve which is authoritative rather than letting traversal order decide.`);
+        this.name = 'AmbiguousInheritanceError';
+        this.field_path = field_path;
+        this.ancestors = ancestors;
+    }
+}
+/**
+ * Select the inherited value for `field_path`: the nearest ancestor wins.
+ *
+ * Exported because a host often needs the winning ancestor's identity to stamp
+ * `_meta.inherited_from`, not merely the value.
+ */
+export function selectInheritedAssumption(field_path, inherited) {
+    const holders = inherited.filter((a) => Object.hasOwn(a.values, field_path));
+    if (holders.length === 0)
+        return null;
+    let nearest = holders[0];
+    for (const candidate of holders.slice(1)) {
+        if (candidate.distance < nearest.distance)
+            nearest = candidate;
+    }
+    const tied = holders.filter((a) => a.distance === nearest.distance && a.document_id !== nearest.document_id);
+    if (tied.length > 0) {
+        throw new AmbiguousInheritanceError(field_path, [nearest, ...tied].map((a) => a.document_id).sort());
+    }
+    return nearest;
+}
 // ─── Internal helpers ────────────────────────────────────────────────────────
 function getBlock(parsed, sectionId) {
     const entry = parsed.sections[sectionId];
@@ -81,12 +122,16 @@ function findBySource(parsed, field_path, wanted) {
  *
  * Cascade order:
  *   1. user_override (in-file, source-tag match)
- *   2. user_input (in-file, source-tag match)
- *   3. investor_profile (ctx.profile)
- *   4. market_data (ctx.market)
- *   5. asset_class_default (defaults registry)
- *   6. global_default (ctx.global)
- *   7. system_default (ctx.system)
+ *   2. user_input (in-file, source-tag match; also market_data_accepted)
+ *   3. inherited_assumption (ctx.inherited — composition DAG only)
+ *   4. investor_profile (ctx.profile)
+ *   5. market_data (ctx.market)
+ *   6. asset_class_default (defaults registry)
+ *   7. global_default (ctx.global)
+ *   8. system_default (ctx.system)
+ *
+ * Throws `AmbiguousInheritanceError` when two equidistant ancestors assert the
+ * same field — the one case where resolution refuses rather than choosing.
  *
  * Returns `undefined` value with step='system_default' as a sentinel only when
  * every step misses; callers SHOULD treat that as an unresolvable input and
@@ -98,12 +143,45 @@ export function resolveValue(field_path, parsed, ctx = {}) {
     if (override) {
         return { value: override.value, source: 'user_override', step: 'user_override' };
     }
-    // Step 2: user_input (also accept 'manual' as a synonym for typed-in values)
-    const input = findBySource(parsed, field_path, ['user_input', 'manual']);
+    // Step 2: user_input ('manual' is a synonym for typed-in values).
+    //
+    // `market_data_accepted` resolves here too (RFC 0022 §4). It is an in-file
+    // value of record, not a fallback: the analyst accepted one observation of
+    // one vintage, and a later live lookup MUST NOT silently replace it. Placing
+    // it here rather than at step 4 is what makes promotion stop the field being
+    // ranked as an unresolved gap.
+    //
+    // The returned `source` is the tag found, so `market_data_accepted` survives
+    // resolution rather than being flattened into `user_input`. Only the *step*
+    // is shared — the cascade is normatively ordered and a producer must not
+    // reorder it (protocol §IX), so a promoted value is a distinctly tagged value
+    // resolved at an existing step rather than a step of its own. Extending the
+    // cascade is a protocol change, which is what RFC 0021 §5 did for
+    // `inherited_assumption`; RFC 0022 deliberately did not need one.
+    const input = findBySource(parsed, field_path, ['user_input', 'manual', 'market_data_accepted']);
     if (input) {
         return { value: input.value, source: input.source, step: 'user_input' };
     }
-    // Step 3: investor_profile
+    // Step 3: inherited_assumption (RFC 0021 §5).
+    //
+    // Below `user_input`, so a value entered on the deal always wins —
+    // inheritance supplies defaults, never overrides. Above `investor_profile`,
+    // because a named ancestor in this deal's own composition DAG is more
+    // specific than an institution-wide preference set.
+    if (ctx.inherited && ctx.inherited.length > 0) {
+        // Throws on equidistant ancestors rather than picking one. Deliberate: a
+        // silent pick would make the answer depend on traversal order.
+        const ancestor = selectInheritedAssumption(field_path, ctx.inherited);
+        if (ancestor) {
+            return {
+                value: ancestor.values[field_path],
+                source: 'inherited_assumption',
+                step: 'inherited_assumption',
+                resolved_from: ancestor.document_id,
+            };
+        }
+    }
+    // Step 4: investor_profile
     if (ctx.profile && field_path in ctx.profile.values) {
         return {
             value: ctx.profile.values[field_path],
@@ -112,7 +190,7 @@ export function resolveValue(field_path, parsed, ctx = {}) {
             resolved_from: ctx.profile.source_id,
         };
     }
-    // Step 4: market_data
+    // Step 5: market_data
     const asset_class = ctx.asset_class ??
         parsed.frontmatter.asset_class ??
         'multifamily';
@@ -124,6 +202,7 @@ export function resolveValue(field_path, parsed, ctx = {}) {
                 source: 'market_data',
                 step: 'market_data',
                 range: hit.range,
+                ...(hit.source_id ? { resolved_from: hit.source_id } : {}),
             };
         }
     }
@@ -132,7 +211,7 @@ export function resolveValue(field_path, parsed, ctx = {}) {
     if (inFileMarket) {
         return { value: inFileMarket.value, source: 'market_data', step: 'market_data' };
     }
-    // Step 5: asset_class_default
+    // Step 6: asset_class_default
     const table = getAssetClassDefaults(asset_class);
     const range = table?.fields[field_path];
     if (range) {
@@ -144,7 +223,7 @@ export function resolveValue(field_path, parsed, ctx = {}) {
             resolved_from: `${table?.asset_class}@${table?.version}`,
         };
     }
-    // Step 6: global_default
+    // Step 7: global_default
     if (ctx.global && field_path in ctx.global.values) {
         return {
             value: ctx.global.values[field_path],
@@ -152,7 +231,7 @@ export function resolveValue(field_path, parsed, ctx = {}) {
             step: 'global_default',
         };
     }
-    // Step 7: system_default
+    // Step 8: system_default
     if (ctx.system && field_path in ctx.system.values) {
         return {
             value: ctx.system.values[field_path],

package/dist/cascade.js.map

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

package/dist/cli.js

@@ -2,8 +2,8 @@
 // uwmd CLI — command-line interface for .uw.md files
 // Commands: parse, validate, compact, diff, init, summary, render
 // Usage: uwmd <command> <file> [options]
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
+import { resolve, basename, dirname } from 'node:path';
 import { parseUWFile } from './parser.js';
 import { validateUWFile } from './validator.js';
 import { compact, diff } from './compactor.js';
@@ -24,6 +24,8 @@ import { runBancroftAgent } from './agents/bancroft.js';
 import { buildContext } from './context-profiles.js';
 import { rankGaps } from './refinement.js';
 import { resolveValue } from './cascade.js';
+import { parseUWPart, resolveComposition, externalizeSection, stringifyUWPart, UWPART_EXTENSION, } from './composition.js';
+import { createDocumentMarketData, parseMarketDataDocument } from './market-data.js';
 import { getAssetClassDefaults } from './defaults.js';
 import { MULTIFAMILY_PACK, getPackForAssetClass } from './packs/index.js';
 import { issueReceipt, verifyReceipt, assertUWReceipt } from './receipts.js';
@@ -171,7 +173,9 @@ function cmdValidate(file, flags) {
 }
 async function cmdVerify(file, flags) {
     const content = readFile(file);
-    const parsed = parseUWFile(content);
+    // --resolved verifies the assembled record. Without it an externalized
+    // section verifies as a directive, which is not the document anyone means.
+    const parsed = withResolved(parseUWFile(content), file, flags);
     // No flag set → run all three.
     const onlyValidate = flags['validate'] === true;
     const onlyIntegrity = flags['integrity'] === true;
@@ -329,7 +333,11 @@ function cmdSummary(file) {
 }
 async function cmdExport(file, flags) {
     const includeSuperseded = !(flags['no-superseded'] === true || flags['compact'] === true);
-    const loaded = await loadEnvelope(file);
+    // --resolved exports the assembled record. Exporting the directive instead
+    // would ship a document whose rent roll is a list of filenames.
+    const loaded = flags['resolved']
+        ? toUWEnvelope(withResolved(parseUWFile(readFile(file)), file, flags))
+        : await loadEnvelope(file);
     const envelope = includeSuperseded ? loaded : { ...loaded, superseded: {} };
     const text = stringifyUWEnvelope(await stampEnvelopeDigest(envelope));
     // Default output path: swap the .uw.md suffix for .uw.json (fall back to appending).
@@ -419,9 +427,15 @@ async function cmdConvert(file, flags) {
         const projection = projectUWEnvelopeToLite(envelope);
         encoded = projection.content;
         extension = '.uw.md';
-        if (projection.report.lossy) {
+        // Two independent losses, reported separately. A record whose only loss is
+        // an externalized section omits zero *paths*, so folding these together
+        // would print "omitted 0 advanced path(s)" over a missing rent roll.
+        if (projection.report.omitted_paths.length > 0) {
             console.warn(`Warning: Lite projection omitted ${projection.report.omitted_paths.length} advanced path(s).`);
         }
+        if (projection.report.externalized_sections.length > 0) {
+            console.warn(`Warning: Lite projection omitted ${projection.report.externalized_sections.length} externalized section(s), unresolved here: ${projection.report.externalized_sections.join(', ')}.`);
+        }
         if (typeof flags['projection-report'] === 'string') {
             writeFileSync(resolve(flags['projection-report']), JSON.stringify(projection.report, null, 2), 'utf-8');
         }
@@ -644,6 +658,65 @@ function cmdReport(file, flags) {
     console.log(`Rendered ${label} → ${basename(outPath)} (${result.sectionsRendered.length} sections${result.sectionsSkipped.length ? `, skipped: ${result.sectionsSkipped.join(', ')}` : ''})`);
     console.log('For PDF output, use @uwmd/report (uwmd-report) or print this HTML from a browser.');
 }
+/**
+ * Load `--market-data <file>` into a cascade-ready lookup, or return null when
+ * the flag is absent. Exits with a message rather than throwing, so a bad
+ * observation set is a usage error rather than a stack trace.
+ */
+function loadMarketData(flags) {
+    const path = flags['market-data'];
+    if (!path)
+        return null;
+    try {
+        const doc = parseMarketDataDocument(parseUWFile(readFile(path)));
+        return {
+            lookup: createDocumentMarketData(doc),
+            identity: {
+                document_id: doc.document_id,
+                as_of: doc.as_of,
+                provider: doc.provider,
+                geo: doc.geo,
+            },
+        };
+    }
+    catch (e) {
+        console.error(`Market data: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+}
+function cmdMarketDataValidate(file, flags) {
+    const parsed = parseUWFile(readFile(file));
+    try {
+        const doc = parseMarketDataDocument(parsed);
+        if (flags['json']) {
+            process.stdout.write(`${JSON.stringify({ valid: true, ...doc }, null, 2)}\n`);
+        }
+        else {
+            console.log(`OK  ${doc.document_id}`);
+            console.log(`    as of ${doc.as_of} — ${doc.provider}`);
+            console.log(`    ${doc.geo}${doc.asset_class ? ` — ${doc.asset_class}` : ''}`);
+            console.log(`    ${doc.observations.length} observation(s):`);
+            for (const o of doc.observations) {
+                console.log(`      ${o.field_path} = ${String(o.value)} ${o.unit}${o.confidence ? ` (${o.confidence})` : ''}`);
+                console.log(`        basis: ${o.basis}`);
+            }
+            // Restated on every run because it is the thing people forget.
+            console.log('\n    Attributable, not verified: this says the observations');
+            console.log('    are traceable, not that they are accurate or current.');
+        }
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (flags['json']) {
+            process.stdout.write(`${JSON.stringify({ valid: false, error: message }, null, 2)}\n`);
+        }
+        else {
+            console.error(`INVALID  ${file}`);
+            console.error(`         ${message}`);
+        }
+        process.exit(1);
+    }
+}
 function cmdScope(file, flags) {
     const content = readFile(file);
     const parsed = parseUWFile(content);
@@ -655,12 +728,19 @@ function cmdScope(file, flags) {
         console.error(`No published asset-class default table for '${assetClass}'.`);
         process.exit(1);
     }
+    const market = loadMarketData(flags);
     const out = {};
     for (const path of Object.keys(table.fields)) {
-        const r = resolveValue(path, parsed);
+        const r = resolveValue(path, parsed, {
+            asset_class: assetClass,
+            ...(market ? { market: market.lookup } : {}),
+        });
         out[path] = {
             value: r.value,
             step: r.step,
+            // Surfaced so a promoted value stays distinguishable in the output: it
+            // resolves at the `user_input` step but is tagged `market_data_accepted`.
+            source: r.source,
             range: r.range,
             resolved_from: r.resolved_from,
         };
@@ -670,6 +750,7 @@ function cmdScope(file, flags) {
         deal_stage_target: 'scope',
         asset_class: assetClass,
         defaults_table: `${assetClass}@${table.version}`,
+        ...(market ? { market_data: market.identity } : {}),
         resolved: out,
     };
     const text = JSON.stringify(payload, null, 2);
@@ -692,7 +773,16 @@ function cmdRefine(file, flags) {
         parsed.frontmatter.asset_class ??
         'multifamily';
     const pack = getPackForAssetClass(assetClass) ?? MULTIFAMILY_PACK;
-    const result = rankGaps(parsed, { targets, top, packs: [pack] });
+    // With `--market-data`, a field the observation set covers is no longer a
+    // gap the cascade cannot fill, so it drops out of the VOI ranking. That is
+    // the point: the ranking should tell you what is still worth diligencing.
+    const market = loadMarketData(flags);
+    const result = rankGaps(parsed, {
+        targets,
+        top,
+        packs: [pack],
+        ...(market ? { cascadeContext: { asset_class: assetClass, market: market.lookup } } : {}),
+    });
     if (flags['json']) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
         return;
@@ -729,6 +819,137 @@ for (let _i = 0; _i < args.length; _i++) {
     } // skip flag + its value
     positional.push(a);
 }
+// ─── Composition (RFC 0021) ──────────────────────────────────────────────────
+/** Load every `.uwpart.md` in a directory, keyed by `part_id`. */
+function loadPartsDir(dir) {
+    const parts = new Map();
+    if (!existsSync(dir))
+        return parts;
+    for (const file of readdirSync(dir).filter((f) => f.endsWith(UWPART_EXTENSION)).sort()) {
+        const path = resolve(dir, file);
+        const part = parseUWPart(parseUWFile(readFileSync(path, 'utf-8')), { filename: file });
+        if (parts.has(part.part_id)) {
+            console.error(`Duplicate part_id '${part.part_id}' in ${dir}`);
+            process.exit(1);
+        }
+        parts.set(part.part_id, part);
+    }
+    return parts;
+}
+/** Where fragments live for a record, unless told otherwise. */
+function defaultPartsDir(file) {
+    return resolve(dirname(resolve(file)), 'parts');
+}
+function cmdCompose(file, flags) {
+    const section = flags['externalize'];
+    if (typeof section !== 'string') {
+        console.error('Usage: uwmd compose <file> --externalize <section> [--collection-key <k>] [--collection-path <p>]');
+        process.exit(1);
+    }
+    const collectionKey = flags['collection-key'] ?? 'unit_id';
+    const collectionPath = flags['collection-path'] ?? 'units';
+    const parsed = parseUWFile(readFile(file));
+    let result;
+    try {
+        result = externalizeSection(parsed, {
+            section,
+            collectionKey,
+            collectionPath,
+            ...(flags['part-prefix'] ? { partIdPrefix: flags['part-prefix'] } : {}),
+        });
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+    const outDir = flags['out-dir'] ? resolve(flags['out-dir']) : defaultPartsDir(file);
+    const recordPath = flags['in-place']
+        ? resolve(file)
+        : flags['output']
+            ? resolve(flags['output'])
+            : resolve(replaceUWExtension(file, '.externalized.uwx.md'));
+    const recordText = stringifyUWX(toUWEnvelope(result.document));
+    if (flags['dry-run']) {
+        console.log(`Would write ${result.parts.length} fragment(s) to ${outDir}:`);
+        for (const part of result.parts)
+            console.log(`  ${part.part_id}${UWPART_EXTENSION}`);
+        console.log(`Would write the record to ${recordPath}`);
+        return;
+    }
+    mkdirSync(outDir, { recursive: true });
+    for (const part of result.parts) {
+        writeFileSync(resolve(outDir, `${part.part_id}${UWPART_EXTENSION}`), stringifyUWPart(part), 'utf-8');
+    }
+    writeFileSync(recordPath, recordText, 'utf-8');
+    console.log(`Externalized ${section} → ${result.parts.length} fragment(s) in ${basename(outDir)}/`);
+    console.log(`Record written to ${basename(recordPath)}`);
+    // Externalizing is a packaging decision, not a model change — worth saying,
+    // because the file looks dramatically different afterwards.
+    console.log('The resolved record has the same semantic digest as the original.');
+}
+function cmdResolve(file, flags) {
+    const partsDir = flags['parts'] ? resolve(flags['parts']) : defaultPartsDir(file);
+    const parsed = parseUWFile(readFile(file));
+    let parts;
+    try {
+        parts = loadPartsDir(partsDir);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+    const resolution = resolveComposition(parsed, { parts });
+    if (flags['json']) {
+        process.stdout.write(`${JSON.stringify({
+            status: resolution.status,
+            externalized: resolution.externalized,
+            parts_available: parts.size,
+            issues: resolution.issues,
+        }, null, 2)}\n`);
+    }
+    else {
+        console.log(`${resolution.status === 'resolved' ? 'RESOLVED' : 'UNRESOLVED'}  ${basename(file)}`);
+        console.log(`    ${parts.size} fragment(s) available in ${basename(partsDir)}/`);
+        console.log(`    externalized section(s): ${resolution.externalized.join(', ') || '(none)'}`);
+        for (const issue of resolution.issues) {
+            console.log(`    [${issue.code}] ${issue.message}`);
+        }
+        if (resolution.status === 'unresolved') {
+            // The rule worth restating: under-resolution is never a smaller answer.
+            console.log('\n    Sections stay externalized rather than resolving partially —');
+            console.log('    a collection missing rows would still total and still validate.');
+        }
+    }
+    if (flags['output'] && resolution.status === 'resolved') {
+        const outPath = resolve(flags['output']);
+        writeFileSync(outPath, stringifyUWX(toUWEnvelope(resolution.document)), 'utf-8');
+        if (!flags['json'])
+            console.log(`    resolved record → ${basename(outPath)}`);
+    }
+    if (resolution.status !== 'resolved')
+        process.exit(1);
+}
+/**
+ * Resolve a record's externalized sections before another command reads it.
+ *
+ * Returns the record unchanged when `--resolved` was not requested, so callers
+ * can apply it unconditionally. Exits when resolution fails: verifying or
+ * exporting a partially-resolved record would report on a document that does
+ * not exist.
+ */
+function withResolved(parsed, file, flags) {
+    if (!flags['resolved'])
+        return parsed;
+    const partsDir = flags['parts'] ? resolve(flags['parts']) : defaultPartsDir(file);
+    const resolution = resolveComposition(parsed, { parts: loadPartsDir(partsDir) });
+    if (resolution.status !== 'resolved') {
+        console.error(`Cannot resolve ${basename(file)} against ${basename(partsDir)}/:`);
+        for (const issue of resolution.issues)
+            console.error(`  [${issue.code}] ${issue.message}`);
+        process.exit(1);
+    }
+    return resolution.document;
+}
 // Top-level async wrapper so `run --live` can use await
 (async () => {
     switch (command) {
@@ -748,7 +969,7 @@ for (let _i = 0; _i < args.length; _i++) {
             break;
         case 'verify':
             if (!positional[0]) {
-                console.error('Usage: uwmd verify <file> [--validate] [--integrity] [--policy] [--json]');
+                console.error('Usage: uwmd verify <file> [--validate] [--integrity] [--policy] [--resolved] [--json]');
                 process.exit(1);
             }
             await cmdVerify(positional[0], flags);
@@ -1020,7 +1241,7 @@ for (let _i = 0; _i < args.length; _i++) {
             break;
         case 'export':
             if (!positional[0]) {
-                console.error('Usage: uwmd export <file.uw.md> [--output <file.uw.json>] [--no-superseded] [--stdout]');
+                console.error('Usage: uwmd export <file.uw.md> [--output <file.uw.json>] [--no-superseded] [--resolved] [--stdout]');
                 process.exit(1);
             }
             await cmdExport(positional[0], flags);
@@ -1044,18 +1265,47 @@ for (let _i = 0; _i < args.length; _i++) {
             break;
         case 'scope':
             if (!positional[0]) {
-                console.error('Usage: uwmd scope <file> [--asset-class multifamily] [--output <file>]');
+                console.error('Usage: uwmd scope <file> [--asset-class multifamily] [--market-data <file>] [--output <file>]');
                 process.exit(1);
             }
             cmdScope(positional[0], flags);
             break;
         case 'refine':
             if (!positional[0]) {
-                console.error('Usage: uwmd refine <file> [--targets dscr,debt_yield] [--top 5] [--json]');
+                console.error('Usage: uwmd refine <file> [--targets dscr,debt_yield] [--top 5] [--market-data <file>] [--json]');
                 process.exit(1);
             }
             cmdRefine(positional[0], flags);
             break;
+        case 'compose':
+            if (!positional[0]) {
+                console.error('Usage: uwmd compose <file> --externalize <section> [--collection-key <k>] [--collection-path <p>] [--out-dir <dir>] [--in-place] [--dry-run]');
+                process.exit(1);
+            }
+            cmdCompose(positional[0], flags);
+            break;
+        case 'resolve':
+            if (!positional[0]) {
+                console.error('Usage: uwmd resolve <file> [--parts <dir>] [--output <file>] [--json]');
+                process.exit(1);
+            }
+            cmdResolve(positional[0], flags);
+            break;
+        case 'market-data': {
+            const sub = positional[0];
+            if (sub === 'validate') {
+                if (!positional[1]) {
+                    console.error('Usage: uwmd market-data validate <file> [--json]');
+                    process.exit(1);
+                }
+                cmdMarketDataValidate(positional[1], flags);
+            }
+            else {
+                console.error('Usage: uwmd market-data validate <file> [--json]');
+                process.exit(1);
+            }
+            break;
+        }
         case 'lease': {
             const sub = positional[0];
             if (sub === 'validate') {
@@ -1191,6 +1441,8 @@ Commands:
   init                         Generate a blank .uwx.md file
   summary  <file>              Print quick metrics to terminal
   export   <file>              Export a digested UW JSON 1.0 document
+  compose  <file>              Externalize a section into .uwpart.md fragments (RFC 0021)
+  resolve  <file>              Resolve externalized sections from a parts directory (RFC 0021)
   formats                       List registered machine representations
   convert  <file>              Convert Lite/UWX/JSON/XML/CSV bundle representations
   report   <file>              Render the lender package / credit memo HTML (§7.1/§7.2)
@@ -1209,6 +1461,12 @@ Options:
   --strict           Throw on parse errors instead of collecting
   --format <f>       Render format: json|csv|chat|summary (render, default: summary)
   --no-superseded    Drop append-only history from the .uw.json export (export)
+  --resolved         Resolve externalized sections first (verify, export)
+  --parts <dir>      Fragment directory (compose, resolve, --resolved; default: ./parts)
+  --externalize <s>  Section to split into fragments (compose)
+  --collection-key <k>  Row identity field (compose, default: unit_id)
+  --collection-path <p> Field the rows occupy (compose, default: units)
+  --in-place         Overwrite the input record (compose)
   --stdout           Write export/convert output to stdout
   --to <format>       Target: lite|uwx|uw-json|uw-xml|uw-csv-bundle (convert)
   --projection-report Write the UWX-to-Lite omission report as JSON (convert)