@uwmd/core 1.1.0

package/dist/envelope.d.ts

@@ -0,0 +1,51 @@
+import type { ParsedUWFile, UWFenceAnnotation, UWFrontmatter } from './types.js';
+export declare const UW_ENVELOPE_VERSION: "1.0";
+export interface UWEnvelopeBlock {
+    annotation: UWFenceAnnotation;
+    /** Complete fenced JSON object. `_meta` appears here exactly once. */
+    content: Record<string, unknown>;
+    /** Markdown immediately preceding this exact block. */
+    prose?: string;
+}
+export type UWEnvelopeSectionEntry = UWEnvelopeBlock | Record<string, UWEnvelopeBlock>;
+export interface UWDocumentEnvelope {
+    envelope_version: typeof UW_ENVELOPE_VERSION;
+    format_version: string;
+    generated_at?: string;
+    generator?: string;
+    semantic_digest?: string;
+    frontmatter: UWFrontmatter;
+    sections: Record<string, UWEnvelopeSectionEntry>;
+    pipeline_log: UWEnvelopeBlock[];
+    custom_calculations: UWEnvelopeBlock[];
+    custom_scenarios: UWEnvelopeBlock[];
+    extensions: Record<string, UWEnvelopeBlock>;
+    superseded: Record<string, UWEnvelopeBlock[]>;
+    [key: string]: unknown;
+}
+export interface ToEnvelopeOptions {
+    /** Default true. False intentionally emits a compacted, model-lossy archive. */
+    includeSuperseded?: boolean;
+    generatedAt?: string;
+    generator?: string;
+}
+export interface EnvelopeDigestVerification {
+    valid: boolean;
+    expected: string;
+    actual?: string;
+}
+export declare class UWEnvelopeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function toUWEnvelope(parsed: ParsedUWFile, options?: ToEnvelopeOptions): UWDocumentEnvelope;
+export declare function fromUWEnvelope(envelope: UWDocumentEnvelope): ParsedUWFile;
+/** Canonical semantic input. Volatile serialization fields are excluded. */
+export declare function envelopeSemanticValue(envelope: UWDocumentEnvelope): Omit<UWDocumentEnvelope, 'generated_at' | 'generator' | 'semantic_digest'>;
+export declare function canonicalizeUWEnvelope(envelope: UWDocumentEnvelope): string;
+export declare function computeEnvelopeDigest(envelope: UWDocumentEnvelope): Promise<string>;
+export declare function stampEnvelopeDigest(envelope: UWDocumentEnvelope): Promise<UWDocumentEnvelope>;
+export declare function verifyEnvelopeDigest(envelope: UWDocumentEnvelope): Promise<EnvelopeDigestVerification>;
+export declare function areEnvelopesEquivalent(left: UWDocumentEnvelope, right: UWDocumentEnvelope): boolean;
+export declare function assertUWEnvelope(value: unknown): asserts value is UWDocumentEnvelope;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,YAAY,EAEZ,iBAAiB,EACjB,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,mBAAmB,EAAG,KAAc,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,sBAAsB,GAC9B,eAAe,GACf,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEpC,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,OAAO,mBAAmB,CAAC;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,aAAa,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACjD,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,mBAAmB,EAAE,eAAe,EAAE,CAAC;IACvC,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;IAC9C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,iBAAsB,GAC9B,kBAAkB,CAqCpB;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,kBAAkB,GAAG,YAAY,CAoDzE;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,kBAAkB,GAC3B,IAAI,CAAC,kBAAkB,EAAE,cAAc,GAAG,WAAW,GAAG,iBAAiB,CAAC,CAI5E;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAE3E;AAED,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAEzF;AAED,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,0BAA0B,CAAC,CAOrC;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,kBAAkB,EACxB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAET;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,kBAAkB,CAoEpF"}

package/dist/envelope.js

@@ -0,0 +1,213 @@
+// UW Document Envelope — format-neutral semantic model shared by machine codecs.
+import { canonicalizeExact } from './integrity-canonical.js';
+import { sha256TextHex } from './integrity.js';
+export const UW_ENVELOPE_VERSION = '1.0';
+export class UWEnvelopeError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${code}] ${message}`);
+        this.name = 'UWEnvelopeError';
+        this.code = code;
+    }
+}
+export function toUWEnvelope(parsed, options = {}) {
+    const sections = {};
+    for (const [sectionId, entry] of Object.entries(parsed.sections)) {
+        if (isVariantMap(entry)) {
+            sections[sectionId] = Object.fromEntries(Object.entries(entry).map(([variant, block]) => [
+                variant,
+                toEnvelopeBlock(block),
+            ]));
+        }
+        else {
+            sections[sectionId] = toEnvelopeBlock(entry);
+        }
+    }
+    const superseded = {};
+    if (options.includeSuperseded ?? true) {
+        for (const [sectionId, blocks] of Object.entries(parsed.superseded)) {
+            superseded[sectionId] = blocks.map(toEnvelopeBlock);
+        }
+    }
+    return {
+        envelope_version: UW_ENVELOPE_VERSION,
+        format_version: parsed.frontmatter.uw_version ?? '1.1',
+        generated_at: options.generatedAt ?? new Date().toISOString(),
+        generator: options.generator ?? '@uwmd/core',
+        frontmatter: parsed.frontmatter,
+        sections,
+        pipeline_log: parsed.pipeline_log.map(toEnvelopeBlock),
+        custom_calculations: parsed.custom_calculations.map(toEnvelopeBlock),
+        custom_scenarios: parsed.custom_scenarios.map(toEnvelopeBlock),
+        extensions: Object.fromEntries(Object.entries(parsed.extensions).map(([id, block]) => [id, toEnvelopeBlock(block)])),
+        superseded,
+    };
+}
+export function fromUWEnvelope(envelope) {
+    assertUWEnvelope(envelope);
+    const sections = {};
+    const prose = {};
+    for (const [sectionId, entry] of Object.entries(envelope.sections)) {
+        if (isVariantMap(entry)) {
+            const variants = Object.fromEntries(Object.entries(entry).map(([variant, block]) => [
+                variant,
+                fromEnvelopeBlock(block, `${sectionId}.${variant}`),
+            ]));
+            sections[sectionId] = variants;
+            const firstProse = Object.values(variants).find((block) => block.prose.length > 0)?.prose;
+            if (firstProse)
+                prose[sectionId] = firstProse;
+        }
+        else {
+            const block = fromEnvelopeBlock(entry, sectionId);
+            sections[sectionId] = block;
+            if (block.prose.length > 0)
+                prose[sectionId] = block.prose;
+        }
+    }
+    return {
+        frontmatter: envelope.frontmatter,
+        sections,
+        prose,
+        pipeline_log: envelope.pipeline_log.map((block, index) => fromEnvelopeBlock(block, `pipeline_log[${index}]`)),
+        custom_calculations: envelope.custom_calculations.map((block, index) => fromEnvelopeBlock(block, `custom_calculations[${index}]`)),
+        custom_scenarios: envelope.custom_scenarios.map((block, index) => fromEnvelopeBlock(block, `custom_scenarios[${index}]`)),
+        extensions: Object.fromEntries(Object.entries(envelope.extensions).map(([id, block]) => [
+            id,
+            fromEnvelopeBlock(block, `extensions.${id}`),
+        ])),
+        superseded: Object.fromEntries(Object.entries(envelope.superseded).map(([sectionId, blocks]) => [
+            sectionId,
+            blocks.map((block, index) => fromEnvelopeBlock(block, `superseded.${sectionId}[${index}]`)),
+        ])),
+        raw: '',
+    };
+}
+/** Canonical semantic input. Volatile serialization fields are excluded. */
+export function envelopeSemanticValue(envelope) {
+    const { generated_at: _generatedAt, generator: _generator, semantic_digest: _digest, ...semantic } = envelope;
+    return semantic;
+}
+export function canonicalizeUWEnvelope(envelope) {
+    return canonicalizeExact(envelopeSemanticValue(envelope));
+}
+export async function computeEnvelopeDigest(envelope) {
+    return `sha256:${await sha256TextHex(canonicalizeUWEnvelope(envelope))}`;
+}
+export async function stampEnvelopeDigest(envelope) {
+    return { ...envelope, semantic_digest: await computeEnvelopeDigest(envelope) };
+}
+export async function verifyEnvelopeDigest(envelope) {
+    const expected = await computeEnvelopeDigest(envelope);
+    return {
+        valid: envelope.semantic_digest === expected,
+        expected,
+        actual: envelope.semantic_digest,
+    };
+}
+export function areEnvelopesEquivalent(left, right) {
+    return canonicalizeUWEnvelope(left) === canonicalizeUWEnvelope(right);
+}
+export function assertUWEnvelope(value) {
+    if (!isRecord(value)) {
+        throw new UWEnvelopeError('ENVELOPE_NOT_OBJECT', 'Document root must be an object.');
+    }
+    if (value['envelope_version'] !== UW_ENVELOPE_VERSION) {
+        throw new UWEnvelopeError('ENVELOPE_UNSUPPORTED_VERSION', `Expected envelope_version "${UW_ENVELOPE_VERSION}".`);
+    }
+    if (typeof value['format_version'] !== 'string') {
+        throw new UWEnvelopeError('ENVELOPE_MISSING_FORMAT_VERSION', 'format_version must be a string.');
+    }
+    if (!isRecord(value['frontmatter'])) {
+        throw new UWEnvelopeError('ENVELOPE_MISSING_FRONTMATTER', 'frontmatter must be an object.');
+    }
+    if (!isRecord(value['sections'])) {
+        throw new UWEnvelopeError('ENVELOPE_MISSING_SECTIONS', 'sections must be an object.');
+    }
+    for (const [sectionId, entry] of Object.entries(value['sections'])) {
+        if (isRecord(entry) && 'annotation' in entry) {
+            assertEnvelopeBlock(entry, `sections.${sectionId}`);
+            continue;
+        }
+        if (!isRecord(entry) || Object.keys(entry).length === 0) {
+            throw new UWEnvelopeError('ENVELOPE_INVALID_VARIANTS', `sections.${sectionId} must be a block or non-empty variant map.`);
+        }
+        for (const [variant, block] of Object.entries(entry)) {
+            assertEnvelopeBlock(block, `sections.${sectionId}.${variant}`);
+        }
+    }
+    for (const key of ['pipeline_log', 'custom_calculations', 'custom_scenarios']) {
+        const collection = value[key];
+        if (!Array.isArray(collection)) {
+            throw new UWEnvelopeError('ENVELOPE_MISSING_COLLECTION', `${key} must be an array.`);
+        }
+        collection.forEach((block, index) => assertEnvelopeBlock(block, `${key}[${index}]`));
+    }
+    if (!isRecord(value['extensions'])) {
+        throw new UWEnvelopeError('ENVELOPE_MISSING_COLLECTION', 'extensions must be an object.');
+    }
+    for (const [id, block] of Object.entries(value['extensions'])) {
+        assertEnvelopeBlock(block, `extensions.${id}`);
+    }
+    if (!isRecord(value['superseded'])) {
+        throw new UWEnvelopeError('ENVELOPE_MISSING_COLLECTION', 'superseded must be an object.');
+    }
+    for (const [sectionId, blocks] of Object.entries(value['superseded'])) {
+        if (!Array.isArray(blocks)) {
+            throw new UWEnvelopeError('ENVELOPE_INVALID_SUPERSEDED', `superseded.${sectionId} must be an array.`);
+        }
+        blocks.forEach((block, index) => assertEnvelopeBlock(block, `superseded.${sectionId}[${index}]`));
+    }
+    const digest = value['semantic_digest'];
+    if (digest !== undefined && (typeof digest !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(digest))) {
+        throw new UWEnvelopeError('ENVELOPE_INVALID_DIGEST', 'semantic_digest must be sha256 followed by 64 lowercase hex characters.');
+    }
+}
+function assertEnvelopeBlock(value, pointer) {
+    if (!isRecord(value) || !isRecord(value['annotation']) || !isRecord(value['content'])) {
+        throw new UWEnvelopeError('ENVELOPE_INVALID_BLOCK', `${pointer} is not a valid block.`);
+    }
+    if (typeof value['annotation']['section'] !== 'string') {
+        throw new UWEnvelopeError('ENVELOPE_INVALID_ANNOTATION', `${pointer}.annotation.section must be a string.`);
+    }
+    if (!isRecord(value['content']['_meta'])) {
+        throw new UWEnvelopeError('ENVELOPE_MISSING_META', `${pointer}.content._meta must be an object.`);
+    }
+    if (value['prose'] !== undefined && typeof value['prose'] !== 'string') {
+        throw new UWEnvelopeError('ENVELOPE_INVALID_PROSE', `${pointer}.prose must be a string.`);
+    }
+}
+function toEnvelopeBlock(block) {
+    const output = {
+        annotation: block.annotation,
+        content: block.content,
+    };
+    if (block.prose.length > 0)
+        output.prose = block.prose;
+    return output;
+}
+function fromEnvelopeBlock(block, pointer) {
+    if (!isRecord(block) || !isRecord(block.annotation) || !isRecord(block.content)) {
+        throw new UWEnvelopeError('ENVELOPE_INVALID_BLOCK', `${pointer} is not a valid block.`);
+    }
+    const meta = block.content['_meta'];
+    if (!isRecord(meta)) {
+        throw new UWEnvelopeError('ENVELOPE_MISSING_META', `${pointer}.content._meta must be an object.`);
+    }
+    return {
+        annotation: block.annotation,
+        meta: meta,
+        content: block.content,
+        prose: typeof block.prose === 'string' ? block.prose : '',
+        rawJson: JSON.stringify(block.content),
+        lineStart: 0,
+        lineEnd: 0,
+    };
+}
+function isVariantMap(entry) {
+    return isRecord(entry) && !('annotation' in entry);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

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

package/dist/format.d.ts

@@ -0,0 +1,60 @@
+export interface CurrencyOptions {
+    decimals?: number;
+    symbol?: string;
+    nullDisplay?: string;
+}
+export interface PercentOptions {
+    decimals?: number;
+    multiplier?: number;
+    suffix?: string;
+    nullDisplay?: string;
+}
+export interface RatioOptions {
+    decimals?: number;
+    suffix?: string;
+    nullDisplay?: string;
+}
+export interface CountOptions {
+    nullDisplay?: string;
+}
+export interface DateOptions {
+    style?: 'iso' | 'short' | 'medium' | 'long';
+    nullDisplay?: string;
+    locale?: string;
+}
+export interface NullOptions {
+    nullDisplay?: string;
+}
+/**
+ * Format a currency value. Default: $1,234,567 (no fractional digits).
+ * Pass `decimals: 2` for $1,234,567.00.
+ */
+export declare function formatCurrency(value: unknown, opts?: CurrencyOptions): string;
+/**
+ * Format a percentage. Default: input is a decimal (0.0551), output is "5.51%".
+ * Pass `multiplier: 1` if the input is already in percentage units.
+ */
+export declare function formatPercent(value: unknown, opts?: PercentOptions): string;
+/**
+ * Format a ratio/multiple. Default: 3 decimals + 'x' suffix → "1.109x".
+ * Pass `suffix: ''` for a plain decimal string with no suffix.
+ */
+export declare function formatRatio(value: unknown, opts?: RatioOptions): string;
+/**
+ * Format an integer count. No locale separators by default.
+ */
+export declare function formatCount(value: unknown, opts?: CountOptions): string;
+/**
+ * Format an ISO-8601 date string. Default style 'iso' returns the input unchanged.
+ * Other styles convert to a locale-formatted date.
+ */
+export declare function formatDate(value: unknown, opts?: DateOptions): string;
+/** Returns the configured null-display string. */
+export declare function formatNull(opts?: NullOptions): string;
+/** Format a percent for CSV: raw decimal × 100 with N digits, empty on null. */
+export declare function formatPercentCsv(value: unknown, decimals?: number): string;
+/** Format a number for CSV: raw value, empty on null. */
+export declare function formatNumberCsv(value: unknown): string;
+/** Coerce any value to a display string with null fallback. */
+export declare function formatValue(value: unknown, opts?: NullOptions): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAUD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAW7E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,MAAM,CAO3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAMvE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAIvE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAarE;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAErD;AAMD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,MAAM,CAIrE;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAItD;AAID,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAGtE"}

package/dist/format.js

@@ -0,0 +1,115 @@
+// Canonical display-formatting helpers for the .uw.md format.
+// Pure functions, no I/O. The single source of truth referenced by the renderer
+// and by Part III of UW_PROTOCOL_v1.md (Display Conventions).
+//
+// Conformance rationale: the protocol freezes 'en-US' as the v1 locale and
+// fixes default precision per kind so any conforming implementer renders the
+// same string for the same value.
+const DEFAULT_NULL = 'n/a';
+function toFiniteNumber(value) {
+    if (value == null)
+        return null;
+    const n = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Format a currency value. Default: $1,234,567 (no fractional digits).
+ * Pass `decimals: 2` for $1,234,567.00.
+ */
+export function formatCurrency(value, opts) {
+    const n = toFiniteNumber(value);
+    if (n === null)
+        return opts?.nullDisplay ?? DEFAULT_NULL;
+    const symbol = opts?.symbol ?? '$';
+    if (opts?.decimals != null) {
+        return `${symbol}${n.toLocaleString('en-US', {
+            minimumFractionDigits: opts.decimals,
+            maximumFractionDigits: opts.decimals,
+        })}`;
+    }
+    return `${symbol}${n.toLocaleString('en-US')}`;
+}
+/**
+ * Format a percentage. Default: input is a decimal (0.0551), output is "5.51%".
+ * Pass `multiplier: 1` if the input is already in percentage units.
+ */
+export function formatPercent(value, opts) {
+    const n = toFiniteNumber(value);
+    if (n === null)
+        return opts?.nullDisplay ?? DEFAULT_NULL;
+    const multiplier = opts?.multiplier ?? 100;
+    const decimals = opts?.decimals ?? 2;
+    const suffix = opts?.suffix ?? '%';
+    return `${(n * multiplier).toFixed(decimals)}${suffix}`;
+}
+/**
+ * Format a ratio/multiple. Default: 3 decimals + 'x' suffix → "1.109x".
+ * Pass `suffix: ''` for a plain decimal string with no suffix.
+ */
+export function formatRatio(value, opts) {
+    const n = toFiniteNumber(value);
+    if (n === null)
+        return opts?.nullDisplay ?? DEFAULT_NULL;
+    const decimals = opts?.decimals ?? 3;
+    const suffix = opts?.suffix ?? 'x';
+    return `${n.toFixed(decimals)}${suffix}`;
+}
+/**
+ * Format an integer count. No locale separators by default.
+ */
+export function formatCount(value, opts) {
+    const n = toFiniteNumber(value);
+    if (n === null)
+        return opts?.nullDisplay ?? DEFAULT_NULL;
+    return String(Math.trunc(n));
+}
+/**
+ * Format an ISO-8601 date string. Default style 'iso' returns the input unchanged.
+ * Other styles convert to a locale-formatted date.
+ */
+export function formatDate(value, opts) {
+    if (value == null)
+        return opts?.nullDisplay ?? DEFAULT_NULL;
+    if (typeof value !== 'string')
+        return opts?.nullDisplay ?? DEFAULT_NULL;
+    const style = opts?.style ?? 'iso';
+    if (style === 'iso')
+        return value;
+    const d = new Date(value);
+    if (!Number.isFinite(d.getTime()))
+        return value;
+    const locale = opts?.locale ?? 'en-US';
+    const dtfOpts = style === 'short' ? { dateStyle: 'short' } :
+        style === 'medium' ? { dateStyle: 'medium' } :
+            { dateStyle: 'long' };
+    return d.toLocaleDateString(locale, dtfOpts);
+}
+/** Returns the configured null-display string. */
+export function formatNull(opts) {
+    return opts?.nullDisplay ?? DEFAULT_NULL;
+}
+// ─── CSV-mode helpers ────────────────────────────────────────────────────────
+// CSV cells use empty strings for null (not 'n/a') and emit raw numbers
+// without currency symbols, percent signs, or ratio suffixes.
+/** Format a percent for CSV: raw decimal × 100 with N digits, empty on null. */
+export function formatPercentCsv(value, decimals = 4) {
+    const n = toFiniteNumber(value);
+    if (n === null)
+        return '';
+    return (n * 100).toFixed(decimals);
+}
+/** Format a number for CSV: raw value, empty on null. */
+export function formatNumberCsv(value) {
+    const n = toFiniteNumber(value);
+    if (n === null)
+        return '';
+    return String(n);
+}
+// ─── Generic value coercion ──────────────────────────────────────────────────
+/** Coerce any value to a display string with null fallback. */
+export function formatValue(value, opts) {
+    if (value == null)
+        return opts?.nullDisplay ?? DEFAULT_NULL;
+    return String(value);
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

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

package/dist/gaps.d.ts

@@ -0,0 +1,62 @@
+import type { DealStage, ParsedUWFile } from './types.js';
+export type GapReason = 'missing' | 'illegible' | 'out_of_scope' | 'deferred' | 'blocked_by_dependency' | 'awaiting_external';
+export interface GapItem {
+    section: string;
+    field_path?: string;
+    reason: GapReason;
+    blocks_stage?: DealStage;
+    first_seen?: string;
+    last_checked?: string;
+    owner?: string;
+    note?: string;
+}
+export interface GapSummary {
+    total_open: number;
+    blocking_current_stage: number;
+    blocking_next_stage: number;
+}
+export interface GapsContent {
+    items: GapItem[];
+    summary?: GapSummary;
+}
+export interface InferGapsOptions {
+    /** Stage to evaluate readiness against. Defaults to file's deal_stage,
+     *  falling back to 'scope'. */
+    stage?: DealStage;
+    /** When true, merge with the existing `gaps` section instead of returning
+     *  inferred items only. Dedup key = `(section, field_path ?? '')`. */
+    mergeWithExisting?: boolean;
+    /** Timestamp to stamp on `first_seen` / `last_checked` for newly inferred
+     *  items. Defaults to `new Date().toISOString()`. */
+    now?: string;
+    /** When true, the item's `owner` is left undefined; when false (default),
+     *  inferred items are assigned `agent/gaps-inferrer` as a provenance hint. */
+    unattributed?: boolean;
+}
+/**
+ * Walk the parsed file and produce a normalized list of GapItems by inspecting:
+ *   - STAGE_REQUIREMENTS: required sections / field paths missing at the
+ *     evaluated stage produce reason='missing'.
+ *   - `_meta.provisional`: produces reason='deferred' (placeholder block).
+ *   - `_meta.partial`: produces reason='missing' for the section as a whole,
+ *     unless `field_overrides` enumerate specific paths (then one item per
+ *     override with `reason='illegible'` for illegible, else 'missing').
+ *   - `_meta.field_overrides[]` with reason='missing'|'illegible': one
+ *     GapItem per entry.
+ *
+ * When `mergeWithExisting` is set, the existing `gaps` section is read and
+ * merged. Existing items win on dedup (their `first_seen`, `owner`, `note`
+ * are preserved); the inferrer only refreshes `last_checked`.
+ */
+export declare function inferGaps(parsed: ParsedUWFile, opts?: InferGapsOptions): GapItem[];
+/**
+ * Aggregate counts for fast pipeline routing. Mirrors the `summary` object in
+ * the gaps section schema (spec/schemas/section-gaps.schema.json).
+ */
+export declare function summarizeGaps(items: readonly GapItem[], currentStage: DealStage): GapSummary;
+/**
+ * Pull the typed content out of the file's `gaps` section. Returns null when
+ * the section is absent or malformed.
+ */
+export declare function readGapsContent(parsed: ParsedUWFile): GapsContent | null;
+//# sourceMappingURL=gaps.d.ts.map

package/dist/gaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaps.d.ts","sourceRoot":"","sources":["../src/gaps.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAW,MAAM,YAAY,CAAC;AAEnE,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,WAAW,GACX,cAAc,GACd,UAAU,GACV,uBAAuB,GACvB,mBAAmB,CAAC;AAExB,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AA6BD,MAAM,WAAW,gBAAgB;IAC/B;mCAC+B;IAC/B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;0EACsE;IACtE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;yDACqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;kFAC8E;IAC9E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAmCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,EAAE,CA4JtF;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,YAAY,EAAE,SAAS,GAAG,UAAU,CAa5F;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,GAAG,IAAI,CAMxE"}