@perrylink/dsh-einvoice 0.1.0-alpha.3 → 0.2.0-alpha.1

package/README.md

@@ -2,7 +2,8 @@
 
 File-level Chinese e-invoice ingest, parse and pool for DeepSeek Harness (SKU-04 S1).
 
-> **Status: S1+S2+S3 / public demo (0.1.0-alpha.3).** 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: file-level public demo (0.2.0-alpha.1) — PARTIAL, NOT COUNTED, NOT GA.**
+> This package does **not** implement OCR/scanning, tax-bureau verification/receipt, tax filing, 30-year archive compliance, or real-invoice accuracy claims. `invoice.review_queue` / `invoice.record_receipt` are local-only; the legacy names are deprecated aliases. Customer-evidence work (2 enterprises + 1 bookkeeping firm + 100 real invoices) is **permanently out of scope**. This package is public-only; its acceptance rows are `not counted`. Do not describe it as GA-ready.
 
 ## Install
 
@@ -21,13 +22,15 @@ The bundle inserts one Host row. It requires the base profile's `tools` and `sto
 | `invoice.parse` | Parse old OFD `Attachs/original_invoice.xml` or 数电票 `Tags/CustomTag.xml` + ObjectRef; return eight fields, lines, evidence and unknown fields | R0 |
 | `invoice.query` | Query the invoice pool by entity, period, lifecycle or text | R0 |
 | `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.review_queue` | Queue parsed invoices for manual local review; optional buyer-tax-id mismatch flags. Old `invoice.verify` is a deprecated alias. | R1 local write |
+| `invoice.record_receipt` | Hash a local receipt, append it, move lifecycle to receipt-recorded/quarantined; `verification_source=local_receipt`, `tax_verified=false`; old `invoice.receipt` is a deprecated alias. | 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 |
 
+Client: deferred; see `CLIENT-DECISION.md`. GA: blocked by the customer evidence gate; see `GA-CHECKLIST.md`.
+
 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

@@ -17,10 +17,10 @@ export declare const lineSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const verificationSchema: z.ZodObject<{
     state: z.ZodEnum<{
-        verified: "verified";
-        pending: "pending";
         failed: "failed";
         manual: "manual";
+        pending: "pending";
+        verified: "verified";
     }>;
     queued_at: z.ZodOptional<z.ZodString>;
     updated_at: z.ZodOptional<z.ZodString>;
@@ -32,8 +32,8 @@ export declare const receiptSchema: z.ZodObject<{
     receipt_id: z.ZodString;
     result_code: z.ZodString;
     result: z.ZodEnum<{
-        pass: "pass";
         fail: "fail";
+        pass: "pass";
         unknown: "unknown";
     }>;
     verified_at: z.ZodString;
@@ -45,8 +45,8 @@ export declare const receiptSchema: z.ZodObject<{
 export declare const redlinkSchema: z.ZodObject<{
     blue_id: z.ZodString;
     mode: z.ZodEnum<{
-        manual: "manual";
         auto: "auto";
+        manual: "manual";
     }>;
     amount_delta_cents: z.ZodNumber;
     tax_delta_cents: z.ZodNumber;
@@ -86,18 +86,18 @@ export declare const invoiceSchema: z.ZodObject<{
     unknown_fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     parser_version: z.ZodString;
     lifecycle: z.ZodEnum<{
-        received: "received";
-        parsed: "parsed";
-        verified: "verified";
         archived: "archived";
+        parsed: "parsed";
         quarantined: "quarantined";
+        received: "received";
+        verified: "verified";
     }>;
     verification: z.ZodOptional<z.ZodObject<{
         state: z.ZodEnum<{
-            verified: "verified";
-            pending: "pending";
             failed: "failed";
             manual: "manual";
+            pending: "pending";
+            verified: "verified";
         }>;
         queued_at: z.ZodOptional<z.ZodString>;
         updated_at: z.ZodOptional<z.ZodString>;
@@ -109,8 +109,8 @@ export declare const invoiceSchema: z.ZodObject<{
         receipt_id: z.ZodString;
         result_code: z.ZodString;
         result: z.ZodEnum<{
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
             unknown: "unknown";
         }>;
         verified_at: z.ZodString;
@@ -122,8 +122,8 @@ export declare const invoiceSchema: z.ZodObject<{
     redlink: z.ZodOptional<z.ZodObject<{
         blue_id: z.ZodString;
         mode: z.ZodEnum<{
-            manual: "manual";
             auto: "auto";
+            manual: "manual";
         }>;
         amount_delta_cents: z.ZodNumber;
         tax_delta_cents: z.ZodNumber;
@@ -159,6 +159,7 @@ export declare const finInvoiceSpec: {
             doc_id: string;
             entity_id: string;
             invoice_no: string;
+            invoice_code?: string | undefined;
             issue_date: string;
             buyer: {
                 name: string;
@@ -175,9 +176,9 @@ export declare const finInvoiceSpec: {
             lines: {
                 line_no: number;
                 description: string;
-                amount_cents: number;
                 quantity?: string | undefined;
                 unit_price_cents?: number | undefined;
+                amount_cents: number;
                 tax_rate?: string | undefined;
                 tax_cents?: number | undefined;
             }[];
@@ -185,28 +186,19 @@ export declare const finInvoiceSpec: {
             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;
+            lifecycle: "archived" | "parsed" | "quarantined" | "received" | "verified";
             verification?: {
-                state: "verified" | "pending" | "failed" | "manual";
-                attempts: number;
+                state: "failed" | "manual" | "pending" | "verified";
                 queued_at?: string | undefined;
                 updated_at?: string | undefined;
+                attempts: number;
                 last_result?: string | undefined;
                 manual_reason?: string | undefined;
             } | undefined;
             receipts?: {
                 receipt_id: string;
                 result_code: string;
-                result: "pass" | "fail" | "unknown";
+                result: "fail" | "pass" | "unknown";
                 verified_at: string;
                 operator: string;
                 receipt_sha256: string;
@@ -215,14 +207,22 @@ export declare const finInvoiceSpec: {
             }[] | undefined;
             redlink?: {
                 blue_id: string;
-                mode: "manual" | "auto";
+                mode: "auto" | "manual";
                 amount_delta_cents: number;
                 tax_delta_cents: number;
+                allocation_cents?: number | undefined;
                 bound_at: string;
                 bound_by: string;
-                allocation_cents?: number | undefined;
             } | undefined;
+            source_path: string;
             source_name?: string | undefined;
+            source_sha256: string;
+            source_size: number;
+            created_at: string;
+            updated_at: string;
+            run_id: string;
+            actor: string;
+            evidence_sha256: string;
         }>;
     };
 };

package/lib/plugin/tools.js

@@ -449,7 +449,7 @@ export function createTools(deps) {
         },
     });
     const verify = defineTool({
-        name: 'invoice.verify',
+        name: 'invoice.review_queue',
         description: 'Queue parsed invoices for manual/semi-automatic verification. S2 has no tax-bureau network call: it records a pending local queue and optional entity-tax-id mismatch flags.',
         parameters: {
             invoice_ids: { type: 'array', items: { type: 'string' }, description: 'Optional subset; defaults to parsed invoices' },
@@ -533,7 +533,7 @@ export function createTools(deps) {
         },
     });
     const receipt = defineTool({
-        name: 'invoice.receipt',
+        name: 'invoice.record_receipt',
         description: 'Record a local verification receipt for one parsed invoice: hash the receipt file, append an immutable receipt record, and move the invoice to verified/quarantined. Local R1 write; no tax-bureau write.',
         parameters: {
             invoice_id: { type: 'string', required: true },
@@ -552,6 +552,8 @@ export function createTools(deps) {
                     receipt_sha256: { type: 'string', required: true },
                     duplicate: { type: 'boolean', required: true },
                     lifecycle: { type: 'string', required: true },
+                    verification_source: { type: 'string', required: true },
+                    tax_verified: { type: 'boolean', required: true },
                 },
             },
             render: (_args, value) => text(`receipt ${value.receipt_id} (${value.duplicate ? 'duplicate' : 'recorded'}), invoice=${value.lifecycle}`),
@@ -571,7 +573,7 @@ export function createTools(deps) {
             const receiptSha = sha256Buffer(buffer);
             const existing = (record.receipts ?? []).find((item) => item.receipt_sha256 === receiptSha);
             if (existing) {
-                return { receipt_id: existing.receipt_id, receipt_sha256: receiptSha, duplicate: true, lifecycle: record.lifecycle };
+                return { receipt_id: existing.receipt_id, receipt_sha256: receiptSha, duplicate: true, lifecycle: record.lifecycle, verification_source: 'local_receipt', tax_verified: false };
             }
             const now = new Date().toISOString();
             const receiptRecord = {
@@ -600,7 +602,7 @@ export function createTools(deps) {
                 updated_at: now,
             };
             await deps.table.put(record.doc_id, updated);
-            return { receipt_id: receiptRecord.receipt_id, receipt_sha256: receiptSha, duplicate: false, lifecycle };
+            return { receipt_id: receiptRecord.receipt_id, receipt_sha256: receiptSha, duplicate: false, lifecycle, verification_source: 'local_receipt', tax_verified: false };
         },
     });
     const archiveDir = path.join(deps.baseDir, 'archives');
@@ -891,5 +893,7 @@ export function createTools(deps) {
             };
         },
     });
-    return [ingest, parse, query, dedup, verify, receipt, redlink, archive, check, restore];
+    const legacyVerify = { ...verify, name: 'invoice.verify', description: 'Deprecated alias for invoice.review_queue; local review queue only, no tax-bureau verification.' };
+    const legacyReceipt = { ...receipt, name: 'invoice.receipt', description: 'Deprecated alias for invoice.record_receipt; local receipt only, no tax-bureau verification.' };
+    return [ingest, parse, query, dedup, verify, legacyVerify, receipt, legacyReceipt, redlink, archive, check, restore];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perrylink/dsh-einvoice",
-  "version": "0.1.0-alpha.3",
+  "version": "0.2.0-alpha.1",
   "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",
@@ -79,6 +79,6 @@
     "@deepseek-ai/dsh-util-values": "0.2.1-rc.3",
     "@deepseek-ai/schemastery": "3.18.5",
     "@types/node": "^24.0.0",
-    "typescript": "5.9.3"
+    "typescript": "7.0.2"
   }
 }