@perrylink/dsh-einvoice 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -2,7 +2,7 @@
 
 File-level Chinese e-invoice ingest, parse and pool for DeepSeek Harness (SKU-04 S1).
 
-> **Status: S1+S2 / public demo (0.1.0-alpha.1).** The customer evidence gate (2 enterprises + 1 bookkeeping firm + 100 real invoices) is still PARKED. S1 uses public/open-source and synthetic fixtures; its acceptance rows are `not counted` toward GA. Do not describe this package as GA-ready.
+> **Status: S1+S2+S3 / public demo (0.1.0-alpha.2).** The customer evidence gate (2 enterprises + 1 bookkeeping firm + 100 real invoices) is still PARKED. S1 uses public/open-source and synthetic fixtures; its acceptance rows are `not counted` toward GA. Do not describe this package as GA-ready.
 
 ## Install
 
@@ -23,8 +23,12 @@ The bundle inserts one Host row. It requires the base profile's `tools` and `sto
 | `invoice.dedup` | Group duplicates by invoice number or seller+date+total | R0 |
 | `invoice.verify` | Queue parsed invoices for manual verification; optional buyer-tax-id mismatch flags | R1 local write |
 | `invoice.receipt` | Hash a local receipt, append it, move lifecycle to verified/quarantined; idempotent by receipt bytes | R1 local write |
+| `invoice.redlink` | Bind a negative red invoice to its blue invoice; store deltas | R1 local write |
+| `invoice.archive` | Build a manifest + originals + receipts ZIP under the local archive directory | R1 local write |
+| `invoice.check` | Verify manifest/member hashes, missing files and traversal | R0 |
+| `invoice.restore` | Restore a verified archive into the local restore root | R1 local write |
 
-S3 adds red/blue matching, archive packages and archive checks; S2 verification is manual/local (no tax-bureau network call).
+S3 adds red/blue matching, deterministic archive packages, check and restore. S2 verification is manual/local (no tax-bureau network call).
 
 ## Configuration
 

package/lib/plugin/storage.d.ts

@@ -42,6 +42,18 @@ export declare const receiptSchema: z.ZodObject<{
     receipt_path: z.ZodString;
     recorded_at: z.ZodString;
 }, z.core.$strip>;
+export declare const redlinkSchema: z.ZodObject<{
+    blue_id: z.ZodString;
+    mode: z.ZodEnum<{
+        manual: "manual";
+        auto: "auto";
+    }>;
+    amount_delta_cents: z.ZodNumber;
+    tax_delta_cents: z.ZodNumber;
+    allocation_cents: z.ZodOptional<z.ZodNumber>;
+    bound_at: z.ZodString;
+    bound_by: z.ZodString;
+}, z.core.$strip>;
 export declare const invoiceSchema: z.ZodObject<{
     doc_id: z.ZodString;
     entity_id: z.ZodString;
@@ -107,7 +119,20 @@ export declare const invoiceSchema: z.ZodObject<{
         receipt_path: z.ZodString;
         recorded_at: z.ZodString;
     }, z.core.$strip>>>;
+    redlink: z.ZodOptional<z.ZodObject<{
+        blue_id: z.ZodString;
+        mode: z.ZodEnum<{
+            manual: "manual";
+            auto: "auto";
+        }>;
+        amount_delta_cents: z.ZodNumber;
+        tax_delta_cents: z.ZodNumber;
+        allocation_cents: z.ZodOptional<z.ZodNumber>;
+        bound_at: z.ZodString;
+        bound_by: z.ZodString;
+    }, z.core.$strip>>;
     source_path: z.ZodString;
+    source_name: z.ZodOptional<z.ZodString>;
     source_sha256: z.ZodString;
     source_size: z.ZodNumber;
     created_at: z.ZodString;
@@ -188,6 +213,16 @@ export declare const finInvoiceSpec: {
                 receipt_path: string;
                 recorded_at: string;
             }[] | undefined;
+            redlink?: {
+                blue_id: string;
+                mode: "manual" | "auto";
+                amount_delta_cents: number;
+                tax_delta_cents: number;
+                bound_at: string;
+                bound_by: string;
+                allocation_cents?: number | undefined;
+            } | undefined;
+            source_name?: string | undefined;
         }>;
     };
 };
@@ -204,6 +239,7 @@ export declare function emptyInvoiceRecord(input: {
     docId: string;
     entityId: string;
     sourcePath: string;
+    sourceName: string;
     sha256: string;
     size: number;
     runId: string;

package/lib/plugin/storage.js

@@ -37,6 +37,15 @@ export const receiptSchema = z.object({
     receipt_path: z.string(),
     recorded_at: z.string(),
 });
+export const redlinkSchema = z.object({
+    blue_id: z.string(),
+    mode: z.enum(['auto', 'manual']),
+    amount_delta_cents: z.number().int(),
+    tax_delta_cents: z.number().int(),
+    allocation_cents: z.number().int().optional(),
+    bound_at: z.string(),
+    bound_by: z.string(),
+});
 export const invoiceSchema = z.object({
     doc_id: z.string().min(1),
     entity_id: z.string(),
@@ -57,7 +66,9 @@ export const invoiceSchema = z.object({
     lifecycle: z.enum(['received', 'parsed', 'verified', 'archived', 'quarantined']),
     verification: verificationSchema.optional(),
     receipts: z.array(receiptSchema).optional(),
+    redlink: redlinkSchema.optional(),
     source_path: z.string(),
+    source_name: z.string().optional(),
     source_sha256: z.string(),
     source_size: z.number().int().nonnegative(),
     created_at: z.string(),
@@ -174,6 +185,7 @@ export function emptyInvoiceRecord(input) {
         parser_version: '',
         lifecycle: 'received',
         source_path: input.sourcePath,
+        source_name: input.sourceName,
         source_sha256: input.sha256,
         source_size: input.size,
         created_at: now,

package/lib/plugin/tools.js

@@ -1,8 +1,9 @@
 /** Three S1 model-facing tools: ingest, parse, query. */
 import { createHash } from 'node:crypto';
-import { readFile, realpath, stat } from 'node:fs/promises';
+import { mkdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { unzipSync, zipSync } from 'fflate';
 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';
@@ -81,6 +82,68 @@ function parsedToRecord(record, parsed) {
         evidence_sha256: createHash('sha256').update(canonicalJson(parsed)).digest('hex'),
     };
 }
+function safeZipPath(name) {
+    return !name.startsWith('/') && !name.split('/').includes('..') && !name.includes('\\0');
+}
+function archivePkgId(manifest) {
+    const base = { ...manifest, pkg_id: undefined };
+    return `pkg_${createHash('sha256').update(canonicalJson(base)).digest('hex').slice(0, 16)}`;
+}
+function parseArchive(buffer) {
+    let files;
+    try {
+        files = unzipSync(buffer);
+    }
+    catch {
+        throw new InvoiceError('E_INV_ARCHIVE_INVALID', 'archive is not a readable ZIP');
+    }
+    const raw = files['manifest.json'];
+    if (!raw)
+        throw new InvoiceError('E_INV_ARCHIVE_INVALID', 'archive has no manifest.json');
+    try {
+        const manifest = JSON.parse(Buffer.from(raw).toString('utf8'));
+        if (!manifest || manifest.schema_version !== 1 || !Array.isArray(manifest.members)) {
+            throw new Error('bad manifest');
+        }
+        return { files, manifest };
+    }
+    catch {
+        throw new InvoiceError('E_INV_ARCHIVE_INVALID', 'archive manifest is not valid v1 JSON');
+    }
+}
+function verifyArchive(buffer) {
+    const { files, manifest } = parseArchive(buffer);
+    const expectedPkgId = archivePkgId(manifest);
+    const missing = [];
+    const hashMismatch = [];
+    const dirViolation = [];
+    if (manifest.pkg_id !== expectedPkgId)
+        hashMismatch.push('manifest:pkg_id');
+    for (const member of manifest.members) {
+        for (const file of member.files ?? []) {
+            if (!safeZipPath(file.path)) {
+                dirViolation.push(file.path);
+                continue;
+            }
+            const data = files[file.path];
+            if (!data) {
+                missing.push(file.path);
+                continue;
+            }
+            if (sha256Buffer(Buffer.from(data)) !== file.sha256)
+                hashMismatch.push(file.path);
+        }
+    }
+    return {
+        manifest,
+        pkg_id: manifest.pkg_id,
+        missing,
+        hash_mismatch: hashMismatch,
+        dir_violation: dirViolation,
+        file_count: Object.keys(files).length,
+        signable: missing.length === 0 && hashMismatch.length === 0 && dirViolation.length === 0,
+    };
+}
 export function createTools(deps) {
     const ingest = defineTool({
         name: 'invoice.ingest',
@@ -135,6 +198,7 @@ export function createTools(deps) {
                 docId,
                 entityId,
                 sourcePath: storedPath,
+                sourceName: path.basename(resolved),
                 sha256,
                 size: info.size,
                 runId: runIdOf(exec),
@@ -182,7 +246,7 @@ export function createTools(deps) {
                 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) });
+            const parsed = parser.parse({ buffer, fileName: record.source_name ?? path.basename(record.source_path) });
             assertEightFields(parsed);
             assertUniqueInvoice(deps.table, record.entity_id, parsed.invoice_no, record.doc_id);
             const updated = parsedToRecord(record, parsed);
@@ -539,5 +603,293 @@ export function createTools(deps) {
             return { receipt_id: receiptRecord.receipt_id, receipt_sha256: receiptSha, duplicate: false, lifecycle };
         },
     });
-    return [ingest, parse, query, dedup, verify, receipt];
+    const archiveDir = path.join(deps.baseDir, 'archives');
+    const restoreRoot = path.join(deps.baseDir, 'restore');
+    async function resolveArchiveFile(args) {
+        if (args.path) {
+            let resolved;
+            try {
+                resolved = await realpath(path.resolve(args.path));
+            }
+            catch {
+                throw new InvoiceError('E_INV_ARCHIVE_NOT_FOUND', `archive not found: ${args.path}`);
+            }
+            const rel = path.relative(archiveDir, resolved);
+            if (rel.startsWith('..') || path.isAbsolute(rel)) {
+                throw new InvoiceError('E_INV_PATH_NOT_ALLOWED', `archive is outside the archive directory: ${args.path}`);
+            }
+            return resolved;
+        }
+        if (!args.pkg_id || !/^pkg_[0-9a-f]{16}$/.test(args.pkg_id)) {
+            throw new InvoiceError('E_INV_ARCHIVE_INVALID', 'pkg_id or path is required');
+        }
+        const candidate = path.join(archiveDir, `${args.pkg_id}.zip`);
+        try {
+            await stat(candidate);
+        }
+        catch {
+            throw new InvoiceError('E_INV_ARCHIVE_NOT_FOUND', `archive not found: ${args.pkg_id}`);
+        }
+        return candidate;
+    }
+    const redlink = defineTool({
+        name: 'invoice.redlink',
+        description: 'Bind a negative red invoice to a positive blue invoice by seller and total, store the binding and deltas. Local R1 write; no tax-bureau call.',
+        parameters: {
+            red_id: { type: 'string', required: true },
+            blue_id: { type: 'string' },
+            mode: { type: 'string', enum: ['auto', 'manual'] },
+            allocation_cents: { type: 'number', description: 'Positive allocation; default is the absolute red total' },
+            bound_by: { type: 'string' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    red_id: { type: 'string', required: true },
+                    blue_id: { type: 'string', required: true },
+                    mode: { type: 'string', required: true },
+                    amount_delta_cents: { type: 'number', required: true },
+                    tax_delta_cents: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => text(`redlink ${value.red_id} -> ${value.blue_id}, delta=${value.amount_delta_cents}`),
+        },
+        async execute(args) {
+            const red = deps.table.get(args.red_id);
+            if (!red)
+                throw new InvoiceError('E_INV_DOC_NOT_FOUND', `unknown red invoice: ${args.red_id}`);
+            if (red.total_cents >= 0)
+                throw new InvoiceError('E_INV_REDLINK_UNBOUND', 'red invoice must have a negative total');
+            const mode = args.mode ?? 'auto';
+            const blueId = args.blue_id ?? [...deps.table.entries()]
+                .map(([, record]) => record)
+                .find((record) => record.doc_id !== red.doc_id && record.seller.tax_id === red.seller.tax_id && record.total_cents === -red.total_cents)?.doc_id;
+            if (!blueId)
+                throw new InvoiceError('E_INV_REDLINK_UNBOUND', 'no matching blue invoice found');
+            if (red.redlink && red.redlink.blue_id !== blueId) {
+                throw new InvoiceError('E_INV_REDLINK_BOUND', `red invoice is already bound to ${red.redlink.blue_id}`);
+            }
+            const blue = deps.table.get(blueId);
+            if (!blue)
+                throw new InvoiceError('E_INV_DOC_NOT_FOUND', `unknown blue invoice: ${blueId}`);
+            const allocation = args.allocation_cents ?? -red.total_cents;
+            if (!Number.isInteger(allocation) || allocation <= 0)
+                throw new InvoiceError('E_INV_REDLINK_UNBOUND', 'allocation must be a positive integer');
+            if (allocation > blue.total_cents)
+                throw new InvoiceError('E_INV_REDLINK_OVER', 'red allocation exceeds the blue invoice total');
+            const amountDelta = blue.total_cents + red.total_cents;
+            const taxDelta = blue.tax_cents + red.tax_cents;
+            const now = new Date().toISOString();
+            const updated = {
+                ...red,
+                redlink: {
+                    blue_id: blueId,
+                    mode,
+                    amount_delta_cents: amountDelta,
+                    tax_delta_cents: taxDelta,
+                    allocation_cents: allocation,
+                    bound_at: now,
+                    bound_by: args.bound_by?.trim() || 'invoice.redlink',
+                },
+                updated_at: now,
+            };
+            await deps.table.put(red.doc_id, updated);
+            return { red_id: red.doc_id, blue_id: blueId, mode, amount_delta_cents: amountDelta, tax_delta_cents: taxDelta };
+        },
+    });
+    const archive = defineTool({
+        name: 'invoice.archive',
+        description: 'Build a local deterministic invoice archive ZIP with manifest.json, original files and receipts; hash the manifest and verify the result. Local R1 write; no signing.',
+        parameters: {
+            entity_id: { type: 'string' },
+            period: { type: 'string', description: 'YYYY-MM from issue_date' },
+            template_id: { type: 'string', description: 'default-v1' },
+            include_receipts: { type: 'boolean' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    pkg_id: { type: 'string', required: true },
+                    manifest_sha256: { type: 'string', required: true },
+                    zip_path: { type: 'string', required: true },
+                    file_count: { type: 'number', required: true },
+                    check_state: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => text(`archive ${value.pkg_id}: ${value.file_count} files (${value.check_state})`),
+        },
+        async execute(args) {
+            const selected = [...deps.table.entries()]
+                .map(([, record]) => record)
+                .filter((record) => record.lifecycle !== 'quarantined')
+                .filter((record) => !args.entity_id || record.entity_id === args.entity_id)
+                .filter((record) => !args.period || invoicePeriod(record.issue_date) === args.period);
+            if (selected.length === 0)
+                throw new InvoiceError('E_INV_ARCHIVE_EMPTY', 'no invoices matched the archive filter');
+            const entries = {};
+            const members = [];
+            for (const record of selected) {
+                let sourceBytes;
+                try {
+                    sourceBytes = await readFile(record.source_path);
+                }
+                catch {
+                    throw new InvoiceError('E_INV_ARCHIVE_MISSING_PART', `original missing for ${record.doc_id}`);
+                }
+                const sourceName = record.source_name ?? path.basename(record.source_path);
+                const sourcePath = `members/${record.doc_id}/${sourceName}`;
+                entries[sourcePath] = sourceBytes;
+                const files = [{ path: sourcePath, sha256: sha256Buffer(sourceBytes), size: sourceBytes.length }];
+                if (args.include_receipts !== false) {
+                    for (const item of record.receipts ?? []) {
+                        let receiptBytes;
+                        try {
+                            receiptBytes = await readFile(item.receipt_path);
+                        }
+                        catch {
+                            throw new InvoiceError('E_INV_ARCHIVE_MISSING_PART', `receipt missing for ${record.doc_id}/${item.receipt_id}`);
+                        }
+                        const receiptPath = `members/${record.doc_id}/receipts/${item.receipt_id}${path.extname(item.receipt_path) || '.bin'}`;
+                        entries[receiptPath] = receiptBytes;
+                        files.push({ path: receiptPath, sha256: sha256Buffer(receiptBytes), size: receiptBytes.length });
+                    }
+                }
+                members.push({
+                    doc_id: record.doc_id,
+                    invoice_no: record.invoice_no,
+                    lifecycle: record.lifecycle,
+                    source_sha256: record.source_sha256,
+                    files,
+                });
+            }
+            const base = {
+                schema_version: 1,
+                entity_id: args.entity_id ?? 'ALL',
+                period: args.period ?? 'ALL',
+                template_id: args.template_id ?? 'default-v1',
+                created_at: new Date().toISOString(),
+                created_by: 'invoice.archive',
+                members,
+            };
+            const pkgId = archivePkgId(base);
+            const manifest = { ...base, pkg_id: pkgId };
+            const manifestText = JSON.stringify(manifest, null, 2);
+            entries['manifest.json'] = new TextEncoder().encode(manifestText);
+            const zipBuffer = Buffer.from(zipSync(entries));
+            await mkdir(archiveDir, { recursive: true });
+            const zipPath = path.join(archiveDir, `${pkgId}.zip`);
+            await writeFile(zipPath, zipBuffer);
+            await writeFile(path.join(archiveDir, `${pkgId}.manifest.json`), manifestText);
+            const check = verifyArchive(zipBuffer);
+            return {
+                pkg_id: pkgId,
+                manifest_sha256: sha256Buffer(Buffer.from(manifestText)),
+                zip_path: zipPath,
+                file_count: Object.keys(entries).length,
+                check_state: check.signable ? 'ok' : 'failed',
+            };
+        },
+    });
+    const check = defineTool({
+        name: 'invoice.check',
+        description: 'Verify an archive package: manifest hash, member hashes, missing files and directory traversal. Read-only; does not restore.',
+        parameters: {
+            pkg_id: { type: 'string' },
+            path: { type: 'string', description: 'Optional archive path under the local archive directory' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    pkg_id: { type: 'string', required: true },
+                    missing: { type: 'array', items: { type: 'string' }, required: true },
+                    hash_mismatch: { type: 'array', items: { type: 'string' }, required: true },
+                    dir_violation: { type: 'array', items: { type: 'string' }, required: true },
+                    signable: { type: 'boolean', required: true },
+                    file_count: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => text(`check ${value.pkg_id}: ${value.signable ? 'ok' : 'failed'} (${value.file_count} files)`),
+        },
+        async execute(args) {
+            const zipPath = await resolveArchiveFile(args);
+            const buffer = await readFile(zipPath);
+            const report = verifyArchive(buffer);
+            return {
+                pkg_id: report.pkg_id,
+                missing: report.missing,
+                hash_mismatch: report.hash_mismatch,
+                dir_violation: report.dir_violation,
+                signable: report.signable,
+                file_count: report.file_count,
+            };
+        },
+    });
+    const restore = defineTool({
+        name: 'invoice.restore',
+        description: 'Restore a verified local archive ZIP into a directory under the local restore root, verifying each member hash before writing. Local R1 write.',
+        parameters: {
+            pkg_id: { type: 'string', required: true },
+            target_dir: { type: 'string', description: 'Optional directory under the local restore root' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    pkg_id: { type: 'string', required: true },
+                    restore_dir: { type: 'string', required: true },
+                    restored: { type: 'number', required: true },
+                    mismatches: { type: 'array', items: { type: 'string' }, required: true },
+                },
+            },
+            render: (_args, value) => text(`restore ${value.pkg_id}: ${value.restored} files`),
+        },
+        async execute(args) {
+            const zipPath = await resolveArchiveFile({ pkg_id: args.pkg_id });
+            const buffer = await readFile(zipPath);
+            const { files, manifest } = parseArchive(buffer);
+            const report = verifyArchive(buffer);
+            let target = path.join(restoreRoot, report.pkg_id);
+            if (args.target_dir) {
+                target = path.resolve(args.target_dir);
+                const rel = path.relative(restoreRoot, target);
+                if (rel.startsWith('..') || path.isAbsolute(rel)) {
+                    throw new InvoiceError('E_INV_PATH_NOT_ALLOWED', 'target_dir must be under the local restore root');
+                }
+            }
+            await mkdir(target, { recursive: true });
+            let restored = 0;
+            for (const member of manifest.members) {
+                for (const file of member.files ?? []) {
+                    if (!safeZipPath(file.path))
+                        continue;
+                    const data = files[file.path];
+                    if (!data)
+                        continue;
+                    if (sha256Buffer(Buffer.from(data)) !== file.sha256)
+                        continue;
+                    const destination = path.join(target, file.path);
+                    const rel = path.relative(target, destination);
+                    if (rel.startsWith('..') || path.isAbsolute(rel))
+                        continue;
+                    await mkdir(path.dirname(destination), { recursive: true });
+                    await writeFile(destination, data);
+                    restored += 1;
+                }
+            }
+            return {
+                pkg_id: report.pkg_id,
+                restore_dir: target,
+                restored,
+                mismatches: [...report.missing, ...report.hash_mismatch, ...report.dir_violation],
+            };
+        },
+    });
+    return [ingest, parse, query, dedup, verify, receipt, redlink, archive, check, restore];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perrylink/dsh-einvoice",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "File-level Chinese e-invoice (OFD/XML) ingest, parse and pool for DeepSeek Harness (SKU-04 S1).",
   "type": "module",
   "main": "./lib/plugin/index.js",