@uwmd/core 1.1.2 → 1.5.0

package/dist/cli.js

@@ -2,28 +2,38 @@
 // 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';
 import { generateBlankUWFile } from './init.js';
 import { render } from './renderer.js';
 import { renderReportHtml } from './report.js';
-import { stringifyUWJsonWithDigest } from './uwjson.js';
-import { toUWEnvelope } from './envelope.js';
+import { stringifyUWEnvelope } from './uwjson.js';
+import { stampEnvelopeDigest, toUWEnvelope, } from './envelope.js';
 import { CORE_CODEC_REGISTRY } from './codecs.js';
 import { writeAgentBlock } from './runner.js';
 import { applyEdit } from './editor.js';
 import { verifyChain, verifyProvenance } from './integrity.js';
+import { loadModuleManifest, createModuleRegistry, ModuleRegistryError } from './modules.js';
+import { cmdLeaseValidate, cmdLeaseProject, cmdPackageCreate, cmdPackageVerify, cmdPackageList, cmdPackageToContext, cmdPackageContextValidate, cmdPackageEdges, } from './cli-packages.js';
 import { evaluateCalc } from './calc/index.js';
 import { buildAgentContext, buildAgentPrompt, isContextReady, BANCROFT_LAYERS } from './context.js';
 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';
+import { CORE_VERSION } from './version.js';
+import { detectUWSourceRepresentation, UWX_REPRESENTATION_ID, UW_LITE_SOURCE_DESCRIPTOR, UWX_SOURCE_DESCRIPTOR, UWX_EXTENSION, } from './source-representation.js';
+import { parseUWLite } from './lite.js';
+import { compileUWLite, projectUWEnvelopeToLite, stringifyUWX, } from './lite-bridge.js';
+import { UW_LITE_REPRESENTATION_ID } from './source-representation.js';
 const [, , command, ...args] = process.argv;
 function readFile(path) {
     const resolved = resolve(path);
@@ -71,6 +81,20 @@ function parseFlags(rawArgs) {
 // ─── Commands ─────────────────────────────────────────────────────────────────
 function cmdParse(file, flags) {
     const content = readFile(file);
+    const detection = detectUWSourceRepresentation(content, file);
+    if (detection.representation !== UWX_REPRESENTATION_ID) {
+        const lite = parseUWLite(content);
+        console.log(JSON.stringify({
+            representation: lite.representation,
+            representation_version: lite.representation_version,
+            frontmatter: lite.frontmatter,
+            fields: lite.fields,
+            issues: lite.issues,
+        }, null, flags['compact'] ? 0 : 2));
+        return;
+    }
+    for (const warning of detection.warnings)
+        console.warn(`Warning: ${warning}`);
     const parsed = parseUWFile(content, { strict: flags['strict'] === true });
     const output = {
         frontmatter: parsed.frontmatter,
@@ -83,6 +107,38 @@ function cmdParse(file, flags) {
 }
 function cmdValidate(file, flags) {
     const content = readFile(file);
+    const detection = detectUWSourceRepresentation(content, file);
+    if (detection.representation !== UWX_REPRESENTATION_ID) {
+        const lite = parseUWLite(content);
+        const errors = lite.issues.filter((issue) => issue.severity === 'error');
+        const warnings = lite.issues.filter((issue) => issue.severity === 'warning');
+        const result = {
+            representation: lite.representation,
+            overall_status: errors.length > 0 ? 'errors' : warnings.length > 0 ? 'warnings' : 'clean',
+            issues: lite.issues,
+            errors,
+            warnings,
+        };
+        if (flags['json']) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`\n${result.overall_status.toUpperCase()} - ${basename(file)}\n`);
+        if (result.issues.length === 0) {
+            console.log('No Lite syntax issues found.');
+        }
+        else {
+            for (const issue of result.issues) {
+                const location = issue.line ? ` line ${issue.line}` : '';
+                const field = issue.field_path ? ` [${issue.field_path}]` : '';
+                console.log(`  [${issue.severity.toUpperCase()}]${location}${field} ${issue.code}: ${issue.message}`);
+            }
+        }
+        console.log('');
+        process.exit(errors.length > 0 ? 1 : 0);
+    }
+    for (const warning of detection.warnings)
+        console.warn(`Warning: ${warning}`);
     const parsed = parseUWFile(content);
     const instCfg = loadInstitutionConfig(flags['institution']);
     const result = validateUWFile(parsed, instCfg?.thresholds);
@@ -117,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;
@@ -229,8 +287,13 @@ function cmdInit(flags) {
         dealStage: flags['stage'],
         tier: flags['tier'] ?? 'screener',
     });
+    // generateBlankUWFile() emits structured UWX content, so the default filename
+    // must be .uwx.md. Writing it as .uw.md produced a file the format spec
+    // forbids and detectUWSourceRepresentation() flags as legacy on the next load.
     const filename = flags['output']
-        ?? (flags['name'] ? `${flags['name'].replace(/\s+/g, '-').toLowerCase()}.uw.md` : 'new-deal.uw.md');
+        ?? (flags['name']
+            ? `${flags['name'].replace(/\s+/g, '-').toLowerCase()}${UWX_EXTENSION}`
+            : `new-deal${UWX_EXTENSION}`);
     const outPath = resolve(filename);
     writeFileSync(outPath, content, 'utf-8');
     console.log(`Created: ${outPath}`);
@@ -269,16 +332,18 @@ function cmdSummary(file) {
 `);
 }
 async function cmdExport(file, flags) {
-    const content = readFile(file);
-    const parsed = parseUWFile(content);
-    const text = await stringifyUWJsonWithDigest(parsed, {
-        // --no-superseded or --compact drops the append-only history.
-        includeSuperseded: !(flags['no-superseded'] === true || flags['compact'] === true),
-    });
+    const includeSuperseded = !(flags['no-superseded'] === true || flags['compact'] === true);
+    // --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).
     const outPath = flags['output']
         ? resolve(flags['output'])
-        : resolve(file.endsWith('.uw.md') ? `${file.slice(0, -'.uw.md'.length)}.uw.json` : `${file}.uw.json`);
+        : resolve(replaceUWExtension(file, '.uw.json'));
     if (flags['stdout']) {
         process.stdout.write(text);
         return;
@@ -292,12 +357,33 @@ const FORMAT_ALIASES = {
     csv: 'uw-csv-bundle',
     'csv-bundle': 'uw-csv-bundle',
     'uw-json': 'uw-json',
+    lite: 'uw-lite-markdown',
+    uw: 'uw-lite-markdown',
+    uwx: 'uwx-markdown',
+    'uw-lite': 'uw-lite-markdown',
+    'uw-lite-markdown': 'uw-lite-markdown',
+    'uwx-markdown': 'uwx-markdown',
     'uw-xml': 'uw-xml',
     'uw-csv-bundle': 'uw-csv-bundle',
 };
 async function loadEnvelope(file) {
-    if (file.toLowerCase().endsWith('.uw.md')) {
-        return toUWEnvelope(parseUWFile(readFile(file)));
+    const lower = file.toLowerCase();
+    if (lower.endsWith('.uw.md') || lower.endsWith(UWX_EXTENSION)) {
+        const content = readFile(file);
+        const detection = detectUWSourceRepresentation(content, file);
+        if (detection.representation !== UWX_REPRESENTATION_ID) {
+            const compilation = compileUWLite(parseUWLite(content));
+            if (!compilation.ok) {
+                const issues = compilation.report.issues
+                    .map((issue) => `${issue.code}: ${issue.message}`)
+                    .join('; ');
+                throw new Error(`UW Lite compilation failed: ${issues}`);
+            }
+            return compilation.envelope;
+        }
+        for (const warning of detection.warnings)
+            console.warn(`Warning: ${warning}`);
+        return toUWEnvelope(parseUWFile(content));
     }
     const sourceCodec = CORE_CODEC_REGISTRY.findByFileName(file);
     if (!sourceCodec || !sourceCodec.descriptor.directions.includes('read')) {
@@ -308,9 +394,17 @@ async function loadEnvelope(file) {
         : readFile(file);
     return sourceCodec.decode(input);
 }
+/**
+ * Swap a known UW source extension for `extension`, appending if none matches.
+ *
+ * `.uwx.md` must be in this list. Without it a UWX input fell through to the
+ * append branch, so `uwmd export deal.uwx.md` wrote `deal.uwx.md.uw.json`
+ * rather than `deal.uw.json`. (`.uw.md` does not match a `.uwx.md` filename —
+ * the suffixes genuinely differ — so it was silently a no-op, not a mis-match.)
+ */
 function replaceUWExtension(file, extension) {
     const lower = file.toLowerCase();
-    for (const suffix of ['.uw.csv.zip', '.uw.md', '.uw.json', '.uw.xml']) {
+    for (const suffix of [UWX_EXTENSION, '.uw.csv.zip', '.uw.md', '.uw.json', '.uw.xml']) {
         if (lower.endsWith(suffix))
             return `${file.slice(0, -suffix.length)}${extension}`;
     }
@@ -319,15 +413,45 @@ function replaceUWExtension(file, extension) {
 async function cmdConvert(file, flags) {
     const requested = flags['to'];
     if (typeof requested !== 'string') {
-        throw new Error('convert requires --to uw-json|uw-xml|uw-csv-bundle.');
+        throw new Error('convert requires --to uw-lite-markdown|uwx-markdown|uw-json|uw-xml|uw-csv-bundle.');
     }
     const targetId = FORMAT_ALIASES[requested.toLowerCase()] ?? requested;
-    const target = CORE_CODEC_REGISTRY.get(targetId);
-    if (!target.descriptor.directions.includes('write')) {
-        throw new Error(`Representation ${targetId} is not writable.`);
-    }
     const envelope = await loadEnvelope(file);
-    const encoded = await target.encode(envelope);
+    let encoded;
+    let extension;
+    if (targetId === UWX_REPRESENTATION_ID) {
+        encoded = stringifyUWX(envelope);
+        extension = UWX_EXTENSION;
+    }
+    else if (targetId === UW_LITE_REPRESENTATION_ID) {
+        const projection = projectUWEnvelopeToLite(envelope);
+        encoded = projection.content;
+        extension = '.uw.md';
+        // 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');
+        }
+    }
+    else {
+        const target = CORE_CODEC_REGISTRY.get(targetId);
+        if (!target.descriptor.directions.includes('write')) {
+            throw new Error(`Representation ${targetId} is not writable.`);
+        }
+        const targetEncoded = await target.encode(envelope);
+        if (typeof targetEncoded !== 'string' && !(targetEncoded instanceof Uint8Array)) {
+            throw new Error(`Representation ${targetId} did not produce file-compatible output.`);
+        }
+        encoded = targetEncoded;
+        extension = target.descriptor.file_extensions[0];
+    }
     if (typeof encoded !== 'string' && !(encoded instanceof Uint8Array)) {
         throw new Error(`Representation ${targetId} did not produce file-compatible output.`);
     }
@@ -335,15 +459,174 @@ async function cmdConvert(file, flags) {
         process.stdout.write(typeof encoded === 'string' ? encoded : Buffer.from(encoded));
         return;
     }
-    const extension = target.descriptor.file_extensions[0];
     const outPath = flags['output']
         ? resolve(flags['output'])
         : resolve(replaceUWExtension(file, extension));
     writeFileSync(outPath, encoded, 'utf-8');
     console.log(`Converted ${basename(file)} → ${basename(outPath)} (${targetId})`);
 }
+// ─── Receipts (RFC 0016 / spec/UW_RECEIPT_v1.md) ─────────────────────────────
+async function cmdReceiptIssue(file, flags) {
+    const receipt = await issueReceipt(readFile(file), {
+        filename: file,
+        issuer: `uwmd-cli@${CORE_VERSION}`,
+        ...(typeof flags['issued-at'] === 'string' ? { issued_at: flags['issued-at'] } : {}),
+    });
+    const serialized = `${JSON.stringify(receipt, null, 2)}\n`;
+    if (flags['stdout']) {
+        process.stdout.write(serialized);
+        return;
+    }
+    const outPath = flags['output']
+        ? resolve(flags['output'])
+        : resolve(`${file.replace(/\.(uw|uwx)\.md$/i, '')}.receipt.json`);
+    writeFileSync(outPath, serialized, 'utf-8');
+    const computed = receipt.computation.results.filter((r) => r.computed).length;
+    console.log(`Issued receipt for ${basename(file)} → ${basename(outPath)} ` +
+        `(${receipt.computation.pack}@${receipt.computation.pack_version}, ` +
+        `${computed}/${receipt.computation.results.length} outputs computed)`);
+    console.log('A receipt attests that these outputs follow from this record. It does not attest that the inputs are true.');
+}
+// ─── Modules ──────────────────────────────────────────────────────────────────
+function readManifestFile(path) {
+    try {
+        return { ok: true, manifest: JSON.parse(readFileSync(resolve(path), 'utf-8')) };
+    }
+    catch (e) {
+        return { ok: false, message: e instanceof Error ? e.message : String(e) };
+    }
+}
+function hostTierFlag(flags) {
+    const tier = flags['tier'];
+    return typeof tier === 'string' ? tier : undefined;
+}
+function cmdModulesValidate(files, flags) {
+    const hostTier = hostTierFlag(flags);
+    const reports = files.map((file) => {
+        const read = readManifestFile(file);
+        if (!read.ok) {
+            return { file, ok: false, errors: [{ category: 'module', code: 'CLI-MOD-READ', message: read.message }] };
+        }
+        const result = loadModuleManifest(read.manifest, hostTier ? { hostTier } : {});
+        return { file, ok: result.ok, errors: result.errors };
+    });
+    if (flags['json']) {
+        console.log(JSON.stringify({ modules: reports }, null, 2));
+        process.exit(reports.every((r) => r.ok) ? 0 : 1);
+    }
+    for (const report of reports) {
+        if (report.ok) {
+            console.log(`\nOK - ${basename(report.file)}`);
+            continue;
+        }
+        console.log(`\nERRORS - ${basename(report.file)}`);
+        for (const error of report.errors) {
+            // The pointer is what makes this actionable: it names the exact
+            // declaration that failed, not just the manifest.
+            const at = 'pointer' in error && error.pointer ? ` [${error.pointer}]` : '';
+            console.log(`  ${error.code}${at} ${error.message}`);
+        }
+    }
+    const failed = reports.filter((r) => !r.ok).length;
+    console.log(`\n${reports.length - failed}/${reports.length} manifest(s) loaded${hostTier ? ` against ${hostTier}` : ''}.\n`);
+    process.exit(failed > 0 ? 1 : 0);
+}
+function cmdModulesList(files, flags) {
+    const hostTier = hostTierFlag(flags);
+    const manifests = [];
+    for (const file of files) {
+        const read = readManifestFile(file);
+        if (!read.ok) {
+            console.error(`Cannot read ${basename(file)}: ${read.message}`);
+            process.exit(1);
+        }
+        manifests.push(read.manifest);
+    }
+    let registry;
+    try {
+        registry = createModuleRegistry({ modules: manifests, ...(hostTier ? { hostTier } : {}) });
+    }
+    catch (e) {
+        // Registry construction is all-or-nothing: a bad manifest means there is no
+        // registry to list, so report why rather than printing a partial one.
+        if (e instanceof ModuleRegistryError) {
+            console.error('Registry refused to load:');
+            for (const error of e.errors)
+                console.error(`  ${error.code} ${error.message}`);
+        }
+        else {
+            console.error(e instanceof Error ? e.message : String(e));
+        }
+        process.exit(1);
+    }
+    const rows = registry.modules.map((m) => ({
+        id: m.id,
+        name: m.name,
+        version: m.version,
+        requires_tier: m.requires_tier,
+        asset_classes: m.asset_classes ?? [],
+        calculations: (m.calculations ?? []).length,
+        validations: (m.validations ?? []).length,
+        sections: (m.sections ?? []).length,
+        agent_layers: (m.agent_layers ?? []).length,
+    }));
+    if (flags['json']) {
+        console.log(JSON.stringify({ modules: rows }, null, 2));
+        return;
+    }
+    console.log(`\n${rows.length} module(s) loaded\n`);
+    for (const row of rows) {
+        console.log(`  ${row.id}@${row.version} — ${row.name}`);
+        console.log(`    tier: ${row.requires_tier}`);
+        console.log(`    asset classes: ${row.asset_classes.length ? row.asset_classes.join(', ') : 'class-agnostic'}`);
+        console.log(`    contributes: ${row.calculations} calc, ${row.validations} validation, ` +
+            `${row.sections} section, ${row.agent_layers} agent layer`);
+    }
+    console.log('');
+}
+async function cmdReceiptVerify(file, receiptPath, flags) {
+    let receipt;
+    try {
+        const raw = JSON.parse(readFileSync(resolve(receiptPath), 'utf-8'));
+        assertUWReceipt(raw);
+        receipt = raw;
+    }
+    catch (e) {
+        console.error(`Not a readable receipt: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(2);
+    }
+    const result = await verifyReceipt(receipt, readFile(file), { filename: file });
+    if (flags['json']) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(`Verdict: ${result.verdict.toUpperCase()}`);
+        for (const issue of result.issues) {
+            const detail = issue.expected !== undefined || issue.actual !== undefined
+                ? ` (expected ${issue.expected ?? '—'}, got ${issue.actual ?? '—'})`
+                : '';
+            console.log(`  [${issue.code}] ${issue.message}${detail}`);
+        }
+        if (result.verdict === 'verified') {
+            console.log('\nThis record is unchanged since issuance and its stated outputs follow deterministically\n' +
+                'from its contents. It is NOT a statement that the inputs are true, complete, or approved.');
+        }
+        else if (result.verdict === 'unverifiable') {
+            console.log('\nThis verifier could not decide. That is not a negative result.');
+        }
+    }
+    // 0 verified, 1 failed, 3 unverifiable — so scripts can tell the third state apart.
+    if (result.verdict === 'failed')
+        process.exit(1);
+    if (result.verdict === 'unverifiable')
+        process.exit(3);
+}
 function cmdFormats(flags) {
-    const descriptors = CORE_CODEC_REGISTRY.list();
+    const descriptors = [
+        UW_LITE_SOURCE_DESCRIPTOR,
+        UWX_SOURCE_DESCRIPTOR,
+        ...CORE_CODEC_REGISTRY.list(),
+    ];
     if (flags['json']) {
         console.log(JSON.stringify(descriptors, null, 2));
         return;
@@ -360,10 +643,12 @@ function cmdReport(file, flags) {
         tier: flags['tier'],
         preparedBy: flags['prepared-by'],
     });
-    // Default output path: swap the .uw.md suffix for .report.html.
+    // Default output path: swap the source extension for .report.html. Routed
+    // through replaceUWExtension so every UW source extension is handled in one
+    // place — the inline .uw.md check this replaced missed .uwx.md entirely.
     const outPath = flags['output']
         ? resolve(flags['output'])
-        : resolve(file.endsWith('.uw.md') ? `${file.slice(0, -'.uw.md'.length)}.report.html` : `${file}.report.html`);
+        : resolve(replaceUWExtension(file, '.report.html'));
     if (flags['stdout']) {
         process.stdout.write(result.html);
         return;
@@ -373,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);
@@ -384,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,
         };
@@ -399,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);
@@ -421,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;
@@ -458,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) {
@@ -477,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);
@@ -749,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);
@@ -759,7 +1251,7 @@ for (let _i = 0; _i < args.length; _i++) {
             break;
         case 'convert':
             if (!positional[0]) {
-                console.error('Usage: uwmd convert <file.uw.md|file.uw.json|file.uw.xml|file.uw.csv.zip> --to uw-json|uw-xml|uw-csv-bundle [--output <file>] [--stdout]');
+                console.error('Usage: uwmd convert <file.uw.md|file.uwx.md|file.uw.json|file.uw.xml|file.uw.csv.zip> --to lite|uwx|uw-json|uw-xml|uw-csv-bundle [--projection-report <file>] [--output <file>] [--stdout]');
                 process.exit(1);
             }
             await cmdConvert(positional[0], flags);
@@ -773,21 +1265,168 @@ 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') {
+                if (!positional[1]) {
+                    console.error('Usage: uwmd lease validate <abstract.json> [--json]');
+                    process.exit(1);
+                }
+                cmdLeaseValidate(positional[1], flags);
+            }
+            else if (sub === 'project') {
+                if (!positional[1]) {
+                    console.error('Usage: uwmd lease project <abstract.json> [--compact]');
+                    process.exit(1);
+                }
+                cmdLeaseProject(positional[1], flags);
+            }
+            else {
+                console.error('Usage: uwmd lease <validate|project> <abstract.json>');
+                process.exit(1);
+            }
+            break;
+        }
+        case 'package': {
+            const sub = positional[0];
+            const target = positional[1];
+            if (sub === 'create') {
+                if (!target) {
+                    console.error('Usage: uwmd package create <manifest.json> [--output <file.uwpkg.zip>]');
+                    process.exit(1);
+                }
+                await cmdPackageCreate(target, flags);
+            }
+            else if (sub === 'verify') {
+                if (!target) {
+                    console.error('Usage: uwmd package verify <file.uwpkg.zip> [--json]');
+                    process.exit(1);
+                }
+                await cmdPackageVerify(target, flags);
+            }
+            else if (sub === 'list') {
+                if (!target) {
+                    console.error('Usage: uwmd package list <file.uwpkg.zip> [--json]');
+                    process.exit(1);
+                }
+                cmdPackageList(target, flags);
+            }
+            else if (sub === 'to-context') {
+                if (!target) {
+                    console.error('Usage: uwmd package to-context <file.uwpkg.zip> [--output <file.json>] [--stdout]');
+                    process.exit(1);
+                }
+                cmdPackageToContext(target, flags);
+            }
+            else if (sub === 'validate-context') {
+                if (!target) {
+                    console.error('Usage: uwmd package validate-context <file.uwpkg.context.json> [--json]');
+                    process.exit(1);
+                }
+                cmdPackageContextValidate(target, flags);
+            }
+            else if (sub === 'edges') {
+                if (!target) {
+                    console.error('Usage: uwmd package edges <file.uwpkg.zip>');
+                    process.exit(1);
+                }
+                cmdPackageEdges(target);
+            }
+            else {
+                console.error('Usage: uwmd package <create|verify|list|to-context|validate-context|edges> ...');
+                process.exit(1);
+            }
+            break;
+        }
+        case 'modules': {
+            const sub = positional[0];
+            const files = positional.slice(1);
+            if (sub === 'validate') {
+                if (files.length === 0) {
+                    console.error('Usage: uwmd modules validate <manifest.json...> [--tier <viewer-tier>] [--json]');
+                    process.exit(1);
+                }
+                cmdModulesValidate(files, flags);
+            }
+            else if (sub === 'list') {
+                if (files.length === 0) {
+                    console.error('Usage: uwmd modules list <manifest.json...> [--tier <viewer-tier>] [--json]');
+                    process.exit(1);
+                }
+                cmdModulesList(files, flags);
+            }
+            else {
+                console.error('Usage: uwmd modules <validate|list> <manifest.json...>');
+                process.exit(1);
+            }
+            break;
+        }
+        case 'receipt': {
+            const sub = positional[0];
+            if (sub === 'issue') {
+                if (!positional[1]) {
+                    console.error('Usage: uwmd receipt issue <file> [--output <file.receipt.json>] [--issued-at <iso>] [--stdout]');
+                    process.exit(1);
+                }
+                await cmdReceiptIssue(positional[1], flags);
+            }
+            else if (sub === 'verify') {
+                if (!positional[1] || !positional[2]) {
+                    console.error('Usage: uwmd receipt verify <file> <receipt.json> [--json]');
+                    process.exit(1);
+                }
+                await cmdReceiptVerify(positional[1], positional[2], flags);
+            }
+            else {
+                console.error('Usage: uwmd receipt <issue|verify> ...');
+                process.exit(1);
+            }
+            break;
+        }
         default:
             console.log(`
-uwmd — .uw.md underwriting file toolkit
+uwmd — UW Markdown underwriting file toolkit
 
 Commands:
   parse    <file>              Parse file and output JSON
@@ -799,14 +1438,20 @@ Commands:
   compact  <file>              Strip superseded blocks
   diff     <file-a> <file-b>  Compare two files section by section
   calc     <file> <calc.json>  Evaluate a calc declaration or inline formula (Tier-3)
-  init                         Generate a blank .uw.md file
+  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 Markdown/JSON/XML/CSV bundle representations
+  convert  <file>              Convert Lite/UWX/JSON/XML/CSV bundle representations
   report   <file>              Render the lender package / credit memo HTML (§7.1/§7.2)
   scope    <file>              Resolve every required input via the fallback cascade and emit a triage view
   refine   <file>              Rank gaps by value-of-information for stated calc targets
+  receipt  issue|verify         Issue or verify a detached verification receipt (RFC 0016)
+  modules  validate|list        Validate module manifest files, or list the registry they form
+  lease    validate|project     Validate a lease abstract, or project it to a rent-roll row (RFC 0018)
+  package  create|verify|...    Build, verify, list, or project a UW Deal Package (RFC 0018)
   layers                       List Bancroft agent layers
 
 Options:
@@ -816,8 +1461,17 @@ 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 representation: uw-json|uw-xml|uw-csv-bundle (convert)
+  --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)
+  --issued-at <iso>  Fix the receipt issuance timestamp (receipt issue)
+  --tier <tier>      Host viewer tier to load modules against (modules)
   --max-tokens <n>   Max tokens for chat render (default: 12000)
   --institution <f>  Path to .uw.institution.json config (validate)
   --name <n>         Deal name (init)