@perrylink/dsh-einvoice 0.0.0-stage → 0.1.0-alpha.0

package/lib/plugin/storage.d.ts

@@ -0,0 +1,140 @@
+/** Storage domain and local original-file store for SKU-04 S1. */
+import { z } from 'zod';
+import type { Context } from '@deepseek-ai/cordis';
+import { type InvoiceLine } from '../core/invoice.js';
+export declare const partySchema: z.ZodObject<{
+    name: z.ZodString;
+    tax_id: z.ZodString;
+}, z.core.$strip>;
+export declare const lineSchema: z.ZodObject<{
+    line_no: z.ZodNumber;
+    description: z.ZodString;
+    quantity: z.ZodOptional<z.ZodString>;
+    unit_price_cents: z.ZodOptional<z.ZodNumber>;
+    amount_cents: z.ZodNumber;
+    tax_rate: z.ZodOptional<z.ZodString>;
+    tax_cents: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const invoiceSchema: z.ZodObject<{
+    doc_id: z.ZodString;
+    entity_id: z.ZodString;
+    invoice_no: z.ZodString;
+    invoice_code: z.ZodOptional<z.ZodString>;
+    issue_date: z.ZodString;
+    buyer: z.ZodObject<{
+        name: z.ZodString;
+        tax_id: z.ZodString;
+    }, z.core.$strip>;
+    seller: z.ZodObject<{
+        name: z.ZodString;
+        tax_id: z.ZodString;
+    }, z.core.$strip>;
+    amount_cents: z.ZodNumber;
+    tax_cents: z.ZodNumber;
+    total_cents: z.ZodNumber;
+    currency: z.ZodLiteral<"CNY">;
+    lines: z.ZodArray<z.ZodObject<{
+        line_no: z.ZodNumber;
+        description: z.ZodString;
+        quantity: z.ZodOptional<z.ZodString>;
+        unit_price_cents: z.ZodOptional<z.ZodNumber>;
+        amount_cents: z.ZodNumber;
+        tax_rate: z.ZodOptional<z.ZodString>;
+        tax_cents: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    confidence: z.ZodNumber;
+    field_evidence: z.ZodRecord<z.ZodString, z.ZodString>;
+    unknown_fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    parser_version: z.ZodString;
+    lifecycle: z.ZodEnum<{
+        received: "received";
+        parsed: "parsed";
+        verified: "verified";
+        archived: "archived";
+        quarantined: "quarantined";
+    }>;
+    source_path: z.ZodString;
+    source_sha256: z.ZodString;
+    source_size: z.ZodNumber;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    run_id: z.ZodString;
+    actor: z.ZodString;
+    evidence_sha256: z.ZodString;
+}, z.core.$strip>;
+export type InvoiceRecord = z.infer<typeof invoiceSchema>;
+export type InvoiceTable = {
+    get(key: string): InvoiceRecord | undefined;
+    entries(): IterableIterator<[string, InvoiceRecord]>;
+    keys(): IterableIterator<string>;
+    readonly size: number;
+    put(key: string, value: InvoiceRecord): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    update(key: string, fn: (current: InvoiceRecord) => InvoiceRecord): Promise<InvoiceRecord>;
+};
+export declare const finInvoiceSpec: {
+    name: string;
+    version: number;
+    tables: {
+        invoices: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            doc_id: string;
+            entity_id: string;
+            invoice_no: string;
+            issue_date: string;
+            buyer: {
+                name: string;
+                tax_id: string;
+            };
+            seller: {
+                name: string;
+                tax_id: string;
+            };
+            amount_cents: number;
+            tax_cents: number;
+            total_cents: number;
+            currency: "CNY";
+            lines: {
+                line_no: number;
+                description: string;
+                amount_cents: number;
+                quantity?: string | undefined;
+                unit_price_cents?: number | undefined;
+                tax_rate?: string | undefined;
+                tax_cents?: number | undefined;
+            }[];
+            confidence: number;
+            field_evidence: Record<string, string>;
+            unknown_fields: Record<string, unknown>;
+            parser_version: string;
+            lifecycle: "received" | "parsed" | "verified" | "archived" | "quarantined";
+            source_path: string;
+            source_sha256: string;
+            source_size: number;
+            created_at: string;
+            updated_at: string;
+            run_id: string;
+            actor: string;
+            evidence_sha256: string;
+            invoice_code?: string | undefined;
+        }>;
+    };
+};
+export declare function openInvoiceTable(ctx: Context): Promise<InvoiceTable>;
+/** Generate a ULID-compatible 26-character document id. */
+export declare function newDocId(now?: number): string;
+export declare function sha256Buffer(buffer: Buffer): string;
+export declare function sha256File(filePath: string): Promise<string>;
+export declare function storeOriginal(baseDir: string, sha256: string, extension: string, buffer: Buffer): Promise<string>;
+export declare function findBySha(table: InvoiceTable, sha256: string): InvoiceRecord | undefined;
+export declare function findByInvoiceNo(table: InvoiceTable, entityId: string, invoiceNo: string): InvoiceRecord | undefined;
+export declare function assertUniqueInvoice(table: InvoiceTable, entityId: string, invoiceNo: string, docId: string): void;
+export declare function emptyInvoiceRecord(input: {
+    docId: string;
+    entityId: string;
+    sourcePath: string;
+    sha256: string;
+    size: number;
+    runId: string;
+    actor: string;
+}): InvoiceRecord;
+export declare function recordLines(lines: InvoiceLine[]): InvoiceLine[];

package/lib/plugin/storage.js

@@ -0,0 +1,168 @@
+/** Storage domain and local original-file store for SKU-04 S1. */
+import { createHash, randomBytes } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { InvoiceError } from '../core/invoice.js';
+export const partySchema = z.object({
+    name: z.string(),
+    tax_id: z.string(),
+});
+export const lineSchema = z.object({
+    line_no: z.number().int().nonnegative(),
+    description: z.string(),
+    quantity: z.string().optional(),
+    unit_price_cents: z.number().int().optional(),
+    amount_cents: z.number().int(),
+    tax_rate: z.string().optional(),
+    tax_cents: z.number().int().optional(),
+});
+export const invoiceSchema = z.object({
+    doc_id: z.string().min(1),
+    entity_id: z.string(),
+    invoice_no: z.string(),
+    invoice_code: z.string().optional(),
+    issue_date: z.string(),
+    buyer: partySchema,
+    seller: partySchema,
+    amount_cents: z.number().int(),
+    tax_cents: z.number().int(),
+    total_cents: z.number().int(),
+    currency: z.literal('CNY'),
+    lines: z.array(lineSchema),
+    confidence: z.number(),
+    field_evidence: z.record(z.string(), z.string()),
+    unknown_fields: z.record(z.string(), z.unknown()),
+    parser_version: z.string(),
+    lifecycle: z.enum(['received', 'parsed', 'verified', 'archived', 'quarantined']),
+    source_path: z.string(),
+    source_sha256: z.string(),
+    source_size: z.number().int().nonnegative(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    run_id: z.string(),
+    actor: z.string(),
+    evidence_sha256: z.string(),
+});
+export const finInvoiceSpec = defineDomain({
+    name: 'fin_invoice',
+    version: 1,
+    tables: {
+        invoices: domainTable(invoiceSchema),
+    },
+});
+export async function openInvoiceTable(ctx) {
+    const domain = await ctx.storageDomain.open(finInvoiceSpec);
+    ctx.effect(() => () => domain.close(), 'dsh-einvoice.domainClose');
+    return domain.table('invoices');
+}
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** Generate a ULID-compatible 26-character document id. */
+export function newDocId(now = Date.now()) {
+    let time = now;
+    let timePart = '';
+    for (let index = 0; index < 10; index += 1) {
+        timePart = (CROCKFORD[time % 32] ?? '0') + timePart;
+        time = Math.floor(time / 32);
+    }
+    const bytes = randomBytes(16);
+    let buffer = 0;
+    let bits = 0;
+    let randomPart = '';
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5 && randomPart.length < 16) {
+            bits -= 5;
+            randomPart += CROCKFORD[(buffer >> bits) & 31] ?? '0';
+        }
+    }
+    return timePart + randomPart;
+}
+export function sha256Buffer(buffer) {
+    return createHash('sha256').update(buffer).digest('hex');
+}
+export async function sha256File(filePath) {
+    const hash = createHash('sha256');
+    await new Promise((resolve, reject) => {
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('error', reject);
+        stream.on('end', resolve);
+    });
+    return hash.digest('hex');
+}
+export async function storeOriginal(baseDir, sha256, extension, buffer) {
+    const directory = path.join(baseDir, 'originals');
+    await mkdir(directory, { recursive: true });
+    const safeExtension = extension.replace(/[^a-z0-9.]/gi, '').slice(0, 8);
+    const target = path.join(directory, `${sha256}${safeExtension}`);
+    try {
+        await writeFile(target, buffer, { mode: 0o600, flag: 'wx' });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EEXIST')
+            throw new InvoiceError('E_INV_STORAGE_FAILED', `cannot store original: ${String(error)}`, { retryable: true });
+    }
+    return target;
+}
+export function findBySha(table, sha256) {
+    for (const [, record] of table.entries()) {
+        if (record.source_sha256 === sha256)
+            return record;
+    }
+    return undefined;
+}
+export function findByInvoiceNo(table, entityId, invoiceNo) {
+    for (const [, record] of table.entries()) {
+        if (record.entity_id === entityId && record.invoice_no === invoiceNo)
+            return record;
+    }
+    return undefined;
+}
+export function assertUniqueInvoice(table, entityId, invoiceNo, docId) {
+    if (!invoiceNo)
+        return;
+    const existing = findByInvoiceNo(table, entityId, invoiceNo);
+    if (existing && existing.doc_id !== docId) {
+        throw new InvoiceError('E_INV_DUP_CONFLICT', `invoice ${invoiceNo} already exists for entity ${entityId}`, {
+            needs_review: true,
+            details: { existing_doc_id: existing.doc_id },
+        });
+    }
+}
+export function emptyInvoiceRecord(input) {
+    const now = new Date().toISOString();
+    return {
+        doc_id: input.docId,
+        entity_id: input.entityId,
+        invoice_no: '',
+        issue_date: '',
+        buyer: { name: '', tax_id: '' },
+        seller: { name: '', tax_id: '' },
+        amount_cents: 0,
+        tax_cents: 0,
+        total_cents: 0,
+        currency: 'CNY',
+        lines: [],
+        confidence: 0,
+        field_evidence: {},
+        unknown_fields: {},
+        parser_version: '',
+        lifecycle: 'received',
+        source_path: input.sourcePath,
+        source_sha256: input.sha256,
+        source_size: input.size,
+        created_at: now,
+        updated_at: now,
+        run_id: input.runId,
+        actor: input.actor,
+        evidence_sha256: '',
+    };
+}
+export function recordLines(lines) {
+    return lines.map((line) => ({ ...line }));
+}

package/lib/plugin/tools.d.ts

@@ -0,0 +1,8 @@
+/** Three S1 model-facing tools: ingest, parse, query. */
+import { type InvoiceTable } from './storage.js';
+export interface ToolDeps {
+    table: InvoiceTable;
+    baseDir: string;
+    inputRoots: string[];
+}
+export declare function createTools(deps: ToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/plugin/tools.js

@@ -0,0 +1,304 @@
+/** Three S1 model-facing tools: ingest, parse, query. */
+import { createHash } from 'node:crypto';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { InvoiceError, assertEightFields, canonicalJson, invoicePeriod, } from '../core/invoice.js';
+import { getParser } from '../registry/parsers.js';
+import { assertUniqueInvoice, emptyInvoiceRecord, findBySha, newDocId, recordLines, sha256Buffer, storeOriginal, } from './storage.js';
+const partyOut = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        name: { type: 'string', required: true },
+        tax_id: { type: 'string', required: true },
+    },
+};
+const lineOut = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        line_no: { type: 'number', required: true },
+        description: { type: 'string', required: true },
+        quantity: { type: 'string' },
+        unit_price_cents: { type: 'number' },
+        amount_cents: { type: 'number', required: true },
+        tax_rate: { type: 'string' },
+        tax_cents: { type: 'number' },
+    },
+};
+function text(value) {
+    return [{ type: 'text', text: value }];
+}
+function actorOf(exec) {
+    return exec.agent?.id ? `agent:${exec.agent.id}` : 'local';
+}
+function runIdOf(exec) {
+    return String(exec.callId);
+}
+async function resolveAllowedPath(inputPath, roots) {
+    const absolute = path.resolve(inputPath);
+    let resolved;
+    try {
+        resolved = await realpath(absolute);
+    }
+    catch {
+        throw new InvoiceError('E_INV_FILE_UNREADABLE', `file does not exist: ${inputPath}`);
+    }
+    const resolvedRoots = await Promise.all(roots.map(async (root) => {
+        try {
+            return await realpath(path.resolve(root));
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    const allowed = resolvedRoots.some((root) => root !== undefined && (resolved === root || resolved.startsWith(root + path.sep)));
+    if (!allowed)
+        throw new InvoiceError('E_INV_PATH_NOT_ALLOWED', `path is outside the configured input roots: ${inputPath}`);
+    return resolved;
+}
+function parsedToRecord(record, parsed) {
+    const updatedAt = new Date().toISOString();
+    return {
+        ...record,
+        invoice_no: parsed.invoice_no,
+        invoice_code: parsed.invoice_code,
+        issue_date: parsed.issue_date,
+        buyer: parsed.buyer,
+        seller: parsed.seller,
+        amount_cents: parsed.amount_cents,
+        tax_cents: parsed.tax_cents,
+        total_cents: parsed.total_cents,
+        currency: 'CNY',
+        lines: recordLines(parsed.lines),
+        confidence: parsed.confidence,
+        field_evidence: parsed.field_evidence,
+        unknown_fields: parsed.unknown_fields,
+        parser_version: parsed.parser_version,
+        lifecycle: 'parsed',
+        updated_at: updatedAt,
+        evidence_sha256: createHash('sha256').update(canonicalJson(parsed)).digest('hex'),
+    };
+}
+export function createTools(deps) {
+    const ingest = defineTool({
+        name: 'invoice.ingest',
+        description: 'Ingest one local OFD/XML invoice file into the SKU-04 pool. Computes SHA-256, stores the original under the local pool, and returns the document id. Re-ingesting the same bytes is idempotent.',
+        parameters: {
+            source: {
+                type: 'object',
+                required: true,
+                additionalProperties: false,
+                properties: {
+                    kind: { type: 'string', enum: ['file'], required: true, description: 'S1 accepts one local file' },
+                    path: { type: 'string', required: true, description: 'Local path under the configured input roots' },
+                    sha256: { type: 'string', description: 'Optional expected SHA-256; mismatch is rejected' },
+                },
+            },
+            entity_id: { type: 'string', description: 'Legal entity id; defaults to "default"' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    doc_id: { type: 'string', required: true },
+                    sha256: { type: 'string', required: true },
+                    size: { type: 'number', required: true },
+                    existing: { type: 'boolean', required: true },
+                },
+            },
+            render: (_args, value) => text(`ingested ${value.doc_id} (${value.size} bytes, sha256 ${value.sha256.slice(0, 12)}…${value.existing ? ', existing' : ''})`),
+        },
+        async execute(args, exec) {
+            const resolved = await resolveAllowedPath(args.source.path, deps.inputRoots);
+            const info = await stat(resolved);
+            if (!info.isFile())
+                throw new InvoiceError('E_INV_FILE_UNREADABLE', 'source is not a regular file');
+            if (info.size === 0)
+                throw new InvoiceError('E_INV_FILE_UNREADABLE', 'source file is empty');
+            if (info.size > 50 * 1024 * 1024)
+                throw new InvoiceError('E_INV_FILE_UNREADABLE', 'source file exceeds 50MB');
+            const buffer = await readFile(resolved);
+            const sha256 = sha256Buffer(buffer);
+            if (args.source.sha256 && args.source.sha256.toLowerCase() !== sha256) {
+                throw new InvoiceError('E_INV_STORAGE_FAILED', 'expected sha256 does not match the source file');
+            }
+            const existing = findBySha(deps.table, sha256);
+            if (existing)
+                return { doc_id: existing.doc_id, sha256, size: info.size, existing: true };
+            const docId = newDocId();
+            const entityId = args.entity_id?.trim() || 'default';
+            const storedPath = await storeOriginal(deps.baseDir, sha256, path.extname(resolved), buffer);
+            const record = emptyInvoiceRecord({
+                docId,
+                entityId,
+                sourcePath: storedPath,
+                sha256,
+                size: info.size,
+                runId: runIdOf(exec),
+                actor: actorOf(exec),
+            });
+            await deps.table.put(docId, record);
+            return { doc_id: docId, sha256, size: info.size, existing: false };
+        },
+    });
+    const parse = defineTool({
+        name: 'invoice.parse',
+        description: 'Parse one ingested OFD/XML invoice into the eight fields, line items, field evidence and unknown fields. Supports old OFD invoice XML and 数电票 CustomTag/ObjectRef.',
+        parameters: {
+            doc_id: { type: 'string', required: true },
+            profile: { type: 'string', description: 'Parser profile; S1 uses ofd-zip-xml' },
+            ocr: { type: 'string', enum: ['off'], description: 'S1 does not run OCR' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    doc_id: { type: 'string', required: true },
+                    invoice_no: { type: 'string', required: true },
+                    issue_date: { type: 'string', required: true },
+                    buyer: { ...partyOut, required: true },
+                    seller: { ...partyOut, required: true },
+                    amount_cents: { type: 'number', required: true },
+                    tax_cents: { type: 'number', required: true },
+                    total_cents: { type: 'number', required: true },
+                    currency: { type: 'string', required: true },
+                    lines: { type: 'array', items: lineOut, required: true },
+                    confidence: { type: 'number', required: true },
+                    field_evidence: { type: 'json', required: true },
+                    unknown_fields: { type: 'json', required: true },
+                    parser_version: { type: 'string', required: true },
+                    warnings: { type: 'array', items: { type: 'string' }, required: true },
+                },
+            },
+            render: (_args, value) => text(`parsed ${value.invoice_no || '(no number)'} ${value.seller.name || '(no seller)'} total=${(value.total_cents / 100).toFixed(2)} CNY lines=${value.lines.length} unknown=${Object.keys(value.unknown_fields ?? {}).length}`),
+        },
+        async execute(args, exec) {
+            const record = deps.table.get(args.doc_id);
+            if (!record)
+                throw new InvoiceError('E_INV_DOC_NOT_FOUND', `unknown doc_id: ${args.doc_id}`);
+            const buffer = await readFile(record.source_path);
+            const parser = getParser(args.profile);
+            const parsed = parser.parse({ buffer, fileName: path.basename(record.source_path) });
+            assertEightFields(parsed);
+            assertUniqueInvoice(deps.table, record.entity_id, parsed.invoice_no, record.doc_id);
+            const updated = parsedToRecord(record, parsed);
+            updated.actor = actorOf(exec);
+            updated.run_id = runIdOf(exec);
+            await deps.table.put(record.doc_id, updated);
+            return {
+                doc_id: record.doc_id,
+                invoice_no: parsed.invoice_no,
+                issue_date: parsed.issue_date,
+                buyer: parsed.buyer,
+                seller: parsed.seller,
+                amount_cents: parsed.amount_cents,
+                tax_cents: parsed.tax_cents,
+                total_cents: parsed.total_cents,
+                currency: parsed.currency,
+                lines: parsed.lines,
+                confidence: parsed.confidence,
+                field_evidence: parsed.field_evidence,
+                unknown_fields: parsed.unknown_fields,
+                parser_version: parsed.parser_version,
+                warnings: parsed.warnings,
+            };
+        },
+    });
+    const query = defineTool({
+        name: 'invoice.query',
+        description: 'Query the SKU-04 invoice pool by entity, period, lifecycle or text; returns a stable page.',
+        parameters: {
+            filter: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    entity_id: { type: 'string' },
+                    period: { type: 'string', description: 'YYYY-MM from issue_date' },
+                    lifecycle: { type: 'string', enum: ['received', 'parsed', 'verified', 'archived', 'quarantined'] },
+                    q: { type: 'string', description: 'Case-insensitive text match on invoice number or seller name' },
+                },
+            },
+            cursor: { type: 'string', description: 'Opaque offset cursor' },
+            page: { type: 'number', description: '1..200, default 50' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    rows: {
+                        required: true,
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                doc_id: { type: 'string', required: true },
+                                invoice_no: { type: 'string', required: true },
+                                issue_date: { type: 'string', required: true },
+                                buyer: { ...partyOut, required: true },
+                                seller: { ...partyOut, required: true },
+                                amount_cents: { type: 'number', required: true },
+                                tax_cents: { type: 'number', required: true },
+                                total_cents: { type: 'number', required: true },
+                                lifecycle: { type: 'string', required: true },
+                                parser_version: { type: 'string', required: true },
+                                confidence: { type: 'number', required: true },
+                            },
+                        },
+                    },
+                    total: { type: 'number', required: true },
+                    next_cursor: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => text(`invoice pool: ${value.total} matched, ${value.rows.length} on this page`),
+        },
+        async execute(args) {
+            const pageSize = Math.max(1, Math.min(200, Math.floor(args.page ?? 50)));
+            const offset = Math.max(0, Number.parseInt(args.cursor ?? '0', 10) || 0);
+            const filter = args.filter ?? {};
+            const rows = [...deps.table.entries()]
+                .map(([, record]) => record)
+                .filter((record) => {
+                if (filter.entity_id && record.entity_id !== filter.entity_id)
+                    return false;
+                if (filter.period && invoicePeriod(record.issue_date) !== filter.period)
+                    return false;
+                if (filter.lifecycle && record.lifecycle !== filter.lifecycle)
+                    return false;
+                if (filter.q) {
+                    const queryText = filter.q.toLowerCase();
+                    if (!record.invoice_no.toLowerCase().includes(queryText) && !record.seller.name.toLowerCase().includes(queryText))
+                        return false;
+                }
+                return true;
+            })
+                .sort((a, b) => b.created_at.localeCompare(a.created_at));
+            const total = rows.length;
+            const pageRows = rows.slice(offset, offset + pageSize).map((record) => ({
+                doc_id: record.doc_id,
+                invoice_no: record.invoice_no,
+                issue_date: record.issue_date,
+                buyer: record.buyer,
+                seller: record.seller,
+                amount_cents: record.amount_cents,
+                tax_cents: record.tax_cents,
+                total_cents: record.total_cents,
+                lifecycle: record.lifecycle,
+                parser_version: record.parser_version,
+                confidence: record.confidence,
+            }));
+            const nextOffset = offset + pageRows.length;
+            return {
+                rows: pageRows,
+                total,
+                next_cursor: nextOffset < total ? String(nextOffset) : '',
+            };
+        },
+    });
+    return [ingest, parse, query];
+}

package/lib/registry/parsers.d.ts

@@ -0,0 +1,5 @@
+/** Frozen parser registry: exactly one S1 adapter. */
+import { type ParserAdapter } from '../adapters/ofd-zip-xml.js';
+export declare const DEFAULT_PARSER_ID: string;
+export declare function getParser(id?: string): ParserAdapter;
+export declare function listParsers(): readonly string[];

package/lib/registry/parsers.js

@@ -0,0 +1,20 @@
+/** Frozen parser registry: exactly one S1 adapter. */
+import { ofdZipXmlParser } from '../adapters/ofd-zip-xml.js';
+import { InvoiceError } from '../core/invoice.js';
+const registry = new Map();
+for (const parser of [ofdZipXmlParser]) {
+    if (registry.has(parser.id))
+        throw new Error(`duplicate parser id: ${parser.id}`);
+    registry.set(parser.id, parser);
+}
+Object.freeze([...registry.keys()]);
+export const DEFAULT_PARSER_ID = ofdZipXmlParser.id;
+export function getParser(id = DEFAULT_PARSER_ID) {
+    const parser = registry.get(id);
+    if (!parser)
+        throw new InvoiceError('E_INV_UNKNOWN_IMPL', `unknown parser implementation: ${id}`);
+    return parser;
+}
+export function listParsers() {
+    return [...registry.keys()];
+}