@uwmd/core 1.1.2 → 1.3.0

package/dist/receipts.d.ts

@@ -0,0 +1,216 @@
+import { type UWDocumentEnvelope } from './envelope.js';
+import type { ModuleManifest } from './protocol.js';
+import { type UWSourceRepresentation } from './source-representation.js';
+import type { ParsedUWFile } from './types.js';
+export declare const UW_RECEIPT_VERSION: "1.0";
+/** Canonicalization used for the Lite representation (UW_LITE_SPEC §6). */
+export declare const UW_LITE_CANONICALIZATION: "uw-lite-financial";
+/** Canonicalization used for structured records (Document Envelope 1.0). */
+export declare const UWX_CANONICALIZATION: "uw-envelope-semantic";
+/**
+ * Tolerance for comparing a stated numeric result against recomputation.
+ * Relative for large magnitudes, absolute near zero.
+ *
+ * Since §VIII.5, a *conforming* issuer can never need this: both sides quantize
+ * before comparison, so they agree exactly or disagree materially. It is kept as
+ * defence-in-depth against a third-party issuer running an alternate precision
+ * routine — that lands as a clean `RCP-03` naming the calc rather than an
+ * `RCP-04` digest mismatch that reads as corruption.
+ */
+export declare const RECEIPT_RESULT_TOLERANCE = 0.000001;
+/** The policy set a receipt names when the host applies core's built-in rules. */
+export declare const BUILTIN_POLICY_SET: "builtin";
+export declare const BUILTIN_POLICY_SET_VERSION: "1.0";
+export type UWReceiptCanonicalization = typeof UW_LITE_CANONICALIZATION | typeof UWX_CANONICALIZATION;
+export interface UWReceiptSubject {
+    representation: UWSourceRepresentation;
+    representation_version: string;
+    canonicalization: UWReceiptCanonicalization;
+    canonicalization_version: string;
+    /** `sha256:<64 lowercase hex>` over the exact UTF-8 bytes of the canonical form. */
+    digest: string;
+}
+export interface UWReceiptResult {
+    calc_id: string;
+    /** Null whenever `computed` is false. Never a hand-entered number. */
+    value: number | string | boolean | null;
+    unit?: string;
+    /**
+     * False when the pack declares this output but the record lacks the inputs to
+     * produce it. The calc engine reports that as a successful evaluation to
+     * `null`; a receipt must not let that read as "the pack computed null".
+     */
+    computed: boolean;
+}
+export interface UWReceiptComputation {
+    /** The pack's manifest id, e.g. `org.uwmd.pack.multifamily`. */
+    pack: string;
+    pack_version: string;
+    engine: string;
+    engine_version: string;
+    /**
+     * The UW Protocol version the issuer computed under. Optional, because a
+     * receipt issued before this field existed cannot retroactively claim one —
+     * absence means "unstated", not "non-conforming".
+     *
+     * It exists so the question "are these numbers quantized per §VIII.5?" is
+     * answerable from the receipt alone. `engine_version` cannot answer it: it
+     * only means something to a reader who knows this engine's release history,
+     * which is precisely the reader a third-party issuer does not have. A
+     * protocol version is the one identifier every conforming issuer shares.
+     */
+    protocol_version?: string;
+    results: UWReceiptResult[];
+    /** Cheap corruption check. A verifier MUST recompute rather than trust this. */
+    results_digest: string;
+}
+export interface UWReceiptPolicy {
+    policy_set: string;
+    policy_set_version: string;
+    validation: {
+        errors: number;
+        warnings: number;
+    };
+}
+/** Wire shape shared with RFC 0010 block signatures. */
+export interface UWReceiptSignature {
+    algorithm: string;
+    key_id: string;
+    value: string;
+}
+export interface UWReceipt {
+    receipt_version: typeof UW_RECEIPT_VERSION;
+    subject: UWReceiptSubject;
+    computation: UWReceiptComputation;
+    policy: UWReceiptPolicy;
+    issued_at: string;
+    issuer: string;
+    signature: UWReceiptSignature | null;
+}
+export type ReceiptErrorCode = 'RCP_PARSE_ERRORS' | 'RCP_COMPILE_FAILED' | 'RCP_PACK_UNRESOLVED' | 'RCP_PACK_UNVERSIONED' | 'RCP_NO_CALCULATIONS' | 'RCP_COMPUTATION_FAILED' | 'RCP_MALFORMED';
+/** Typed error, consistent with `ProtocolError` / `CalcError` / `ExcelEmitError`. */
+export declare class ReceiptError extends Error {
+    readonly code: ReceiptErrorCode;
+    constructor(code: ReceiptErrorCode, message: string);
+}
+export type UWReceiptVerdict = 'verified' | 'failed' | 'unverifiable';
+export type UWReceiptIssueCode = 
+/** Subject digest disagrees with the document's canonical form. */
+'RCP-01'
+/** Stated results do not cover exactly the pack's declared outputs. */
+ | 'RCP-02'
+/** A stated result disagrees with recomputation beyond tolerance. */
+ | 'RCP-03'
+/** `results_digest` does not recompute — accidental corruption. */
+ | 'RCP-04'
+/** The named pack is unknown to this verifier. */
+ | 'RCP-05'
+/** The named pack version differs from the one this verifier holds. */
+ | 'RCP-06'
+/** Results disagree and the engine version also differs. */
+ | 'RCP-07'
+/** A signature is present and this verifier has no signature backend. */
+ | 'RCP-08'
+/** The document could not be canonicalized (parse or compile failure). */
+ | 'RCP-09';
+export interface UWReceiptIssue {
+    code: UWReceiptIssueCode;
+    severity: 'failure' | 'indeterminate';
+    message: string;
+    calc_id?: string;
+    expected?: string;
+    actual?: string;
+}
+export interface UWReceiptVerification {
+    verdict: UWReceiptVerdict;
+    issues: UWReceiptIssue[];
+    /** What the verifier itself computed, when it got far enough to compute. */
+    recomputed?: UWReceiptResult[];
+}
+/** Plugged in by a signing package; absent here so core stays crypto-light. */
+export interface ReceiptSignatureVerifier {
+    verify(receipt: UWReceipt, signedPayload: string): Promise<boolean>;
+}
+export interface ReceiptSubjectOptions {
+    /** Filename hint for representation detection. */
+    filename?: string;
+    /** Force a representation instead of detecting it. */
+    representation?: UWSourceRepresentation;
+}
+export interface ReceiptSubjectResolution {
+    subject: UWReceiptSubject;
+    /** Exact canonical bytes the digest covers. */
+    canonical: string;
+    /** Structured view used for calc evaluation and validation. */
+    parsed: ParsedUWFile;
+    envelope: UWDocumentEnvelope;
+}
+/**
+ * Parse, canonicalize, and digest a record. Throws a typed `ReceiptError` when
+ * the document has parse-level errors — an issuer MUST NOT emit a receipt for
+ * such a document (RFC 0016, extending UW_LITE_SPEC §5 to every representation).
+ */
+export declare function resolveReceiptSubject(content: string, options?: ReceiptSubjectOptions): Promise<ReceiptSubjectResolution>;
+/**
+ * Run every calc a pack declares. Throws when any one fails — a receipt states
+ * the pack's complete output set or it states nothing (RFC 0016).
+ */
+export declare function computeReceiptResults(pack: ModuleManifest, parsed: ParsedUWFile): UWReceiptResult[];
+/** SHA-256 over the RFC 8785 canonicalization of the result set. */
+export declare function computeResultsDigest(results: readonly UWReceiptResult[]): Promise<string>;
+export interface ReceiptIssuanceOptions extends ReceiptSubjectOptions {
+    /** Pack override. Defaults to the built-in pack for `frontmatter.asset_class`. */
+    pack?: ModuleManifest;
+    /** Identity of the issuing tool, e.g. `uwmd-cli@1.1.3`. */
+    issuer?: string;
+    /** ISO 8601 instant. Supply explicitly for reproducible fixtures. */
+    issued_at?: string;
+    policy_set?: string;
+    policy_set_version?: string;
+    engine?: string;
+    engine_version?: string;
+    /** Protocol version to state. Defaults to the `PROTOCOL_VERSION` this build targets. */
+    protocol_version?: string;
+}
+/**
+ * Issue an unsigned receipt for a record. Either returns a receipt or throws a
+ * typed `ReceiptError` — never a caveated or partial receipt.
+ */
+export declare function issueReceipt(content: string, options?: ReceiptIssuanceOptions): Promise<UWReceipt>;
+/**
+ * The RFC 8785 canonicalization a signature covers: the receipt with
+ * `signature` set to null.
+ */
+export declare function receiptSigningPayload(receipt: UWReceipt): string;
+export interface ReceiptVerificationOptions extends ReceiptSubjectOptions {
+    /** Packs available to this verifier, keyed by manifest id. Defaults to built-ins. */
+    packs?: readonly ModuleManifest[];
+    /** Supplied by a signing package. Absent → a signed receipt is `unverifiable`. */
+    signatureVerifier?: ReceiptSignatureVerifier;
+    /** Engine identity of this verifier. Defaults to this package. */
+    engine?: string;
+    engine_version?: string;
+}
+/**
+ * Verify a receipt against a record.
+ *
+ * Reports exactly one of three verdicts and never collapses `unverifiable` into
+ * either of the others. Precedence:
+ *
+ *   1. A digest mismatch is decisive — the record changed. `failed`.
+ *   2. Otherwise, anything this verifier cannot decide (unknown pack, pack
+ *      version it does not hold, a signature with no backend) → `unverifiable`.
+ *   3. Otherwise, recomputation disagreement → `failed`, unless the issuing
+ *      engine identity (name *and* version) differs from this verifier's, in
+ *      which case the disagreement is attributable to the engine and the
+ *      verdict is `unverifiable` (RFC 0016 open question, resolved in
+ *      `spec/UW_RECEIPT_v1.md` §5).
+ *   4. Otherwise `verified`.
+ *
+ * The verifier always recomputes; `results_digest` is checked only as a cheap
+ * corruption signal and never authorizes skipping the recomputation.
+ */
+export declare function verifyReceipt(receipt: UWReceipt, content: string, options?: ReceiptVerificationOptions): Promise<UWReceiptVerification>;
+/** Structural check mirroring `spec/schemas/uw-receipt.schema.json`. */
+export declare function assertUWReceipt(value: unknown): asserts value is UWReceipt;
+//# sourceMappingURL=receipts.d.ts.map

package/dist/receipts.d.ts.map

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