@intentproof/sdk 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,9 @@
 ## **Logs narrate; IntentProof gives you proof.**
 
+[![CI](https://github.com/IntentProof/intentproof-sdk-node/actions/workflows/ci.yml/badge.svg)](https://github.com/IntentProof/intentproof-sdk-node/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@intentproof/sdk)](https://www.npmjs.com/package/@intentproof/sdk)
+<a href="https://github.com/IntentProof/intentproof-sdk-node/raw/main/conformance-certificate.json" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/conformance_certificate-view-0366d6" alt="Conformance Certificate" /></a>
+
 **IntentProof** is **auditable execution records** for actions that must be defensible—**intent** tied to what actually ran.
 
 **Wrap** the calls that matter; each invocation emits one **verifiable** **`ExecutionEvent`**, structured so intent and outcome can be **reconciled** with reality—not only observed.
@@ -43,10 +47,7 @@ Ordinary telemetry shows that *something ran*. It rarely ships an **auditable st
 
 **Package:** `@intentproof/sdk`.
 
-- [npm — `@intentproof/sdk`](https://www.npmjs.com/package/@intentproof/sdk)
-- [GitHub Releases — IntentProof Node SDK](https://github.com/IntentProof/intentproof-sdk-node/releases)
-
-Pin the **version** you want from npm or from GitHub Releases. Replace **`x.y.z`** below with that version.
+Replace **`x.y.z`** with the package version you intend to pin.
 
 ```bash
 npm install @intentproof/sdk@x.y.z
@@ -339,7 +340,7 @@ try {
 
 ### 3 — Proof delivery over HTTP (same **`ExecutionEvent`** shape)
 
-**`HttpExporter`** POSTs the same **`ExecutionEvent`** your verifiers see in memory—here alongside **`MemoryExporter`** so tests can assert the wire without a real collector. The request omits ambient credentials; the body is **`{ "intentproof": "1", "event": … }`** (see exporter implementation). For authenticated collectors, pass **`headers`** (e.g. **`Authorization`**, API keys) — see [Security](#security).
+**`HttpExporter`** POSTs the same **`ExecutionEvent`** your verifiers see in memory—here alongside **`MemoryExporter`** so tests can assert the wire without a real collector. The request omits ambient credentials; the body is **`{ "intentproof": "1", "event": … }`** (see exporter implementation). For authenticated collectors, pass **`headers`** (e.g. **`Authorization`**, API keys) — see the Security section above.
 
 ```ts
 const runProbe = client.wrap({ intent: "HTTP test", action: "test.http" }, () => 42);
@@ -360,7 +361,7 @@ runProbe();
 
 ## Security
 
-For **vulnerability reporting**, use this repository’s [**Security**](https://github.com/IntentProof/intentproof-sdk-node/security) tab (private advisories).
+For **vulnerability reporting**, use this repository’s Security tab (private advisories).
 
 Every **`ExecutionEvent`** you emit is data you may ship off-process. Treat them like audit-grade execution records: they can include PII, secrets, stack traces, and business identifiers depending on your **`snapshot`** / **`capture*`** hooks.
 
@@ -377,9 +378,14 @@ Custom **`body`** serializers: if **`body(event)`** throws, **`HttpExporter`** n
 
 ## Canonical specification (`intentproof-spec`)
 
-Schemas, golden oracles, and the **Vitest conformance oracle** live in the **[IntentProof specification repository (`intentproof-spec`)](https://github.com/intentproof/intentproof-spec)**.
+**Shared pins and terminology** (`INTENTPROOF_SPEC_ROOT`, **`intentproofSpecCommit`**, script names) are documented in the **`intentproof-spec`** repository (`CONTRIBUTING.md`, Terminology).
+
+**`intentproof-spec`** holds normative schemas, golden **`execution_event_cases.jsonl`**, and the canonical **`spec-conformance.sh`** toolchain (Vitest/Jest-style harness code used by the spec lives there too).
 
-- **CI:** every push/PR runs `scripts/run-conformance.sh` from that repo (see `.github/workflows/ci.yml`).
+- **Version pin:** **`intentproofSpecVersion`** and **`intentproofSpecCommit`** in the root **`package.json`** and **`packages/sdk/package.json`** match **`spec.json`** and the spec **`HEAD`** checkout; **`scripts/check-sdk-spec-pin.sh`** enforces this before conformance.
+
+- **CI:** every push/PR checks out this SDK plus **`intentproof-spec`** and runs **`scripts/spec-conformance.sh`** (pin check + full oracle; see `.github/workflows/ci.yml`). The **`sdk`** job sets **`INTENTPROOF_SPEC_ROOT`** so **`packages/sdk`** Vitest imports the spec **`sdk_test_harness`**—golden **`execution_event_cases.jsonl`** plus **`MemoryExporter`** **`validateExecutionEvent`** smoke (`spec_conformance.integration.test.ts`).
+- **Repo-root certificates:** each run uploads **`conformance-report.json`** and **`conformance-certificate.json`** as workflow artifacts; after a green default-branch push, the conformance GitHub App commits the same files at the repo root when they differ from **`main`**.
 - **Local:** clone `intentproof-spec` **next to** this repository (`../intentproof-spec`), then:
 
   ```bash
@@ -388,11 +394,21 @@ Schemas, golden oracles, and the **Vitest conformance oracle** live in the **[In
 
   Or set `INTENTPROOF_SPEC_ROOT` to your spec checkout and run `bash scripts/spec-conformance.sh`.
 
+- **Generated fingerprint metadata:** schema codegen writes **`packages/sdk/src/generated/spec_fingerprint.json`** (spec version, generator version, per-schema SHA-256, aggregate hash). Validate/update generated artifacts with:
+
+  ```bash
+  bash scripts/verify-generated-types.sh
+  ```
+
+- **No handwritten model types:** **`scripts/check-no-handwritten-model-types.sh`** delegates to the shared **`intentproof-spec`** checker. It is wired into **`npm run ci`**, CI, and release, and fails if schema model/type declarations appear outside **`packages/sdk/src/generated`** or if the bridge aliases in **`packages/sdk/src/types.ts`** stop mapping to generated types.
+
 ---
 
 ## Project development
 
-Layout: **npm workspace** (`package.json` **`workspaces`**, publishable package [`packages/sdk`](packages/sdk)). Requires **Node.js** 22 or newer (see `.nvmrc` and workspace **`engines`**). Release history: [`CHANGELOG.md`](CHANGELOG.md).
+Contributing and shared **`intentproof-spec`** terminology: see **`CONTRIBUTING.md`**.
+
+Layout: **npm workspace** (`package.json` **`workspaces`**, publishable package **`packages/sdk`**). Requires **Node.js** 22 or newer (see `.nvmrc` and workspace **`engines`**). Release history: **`CHANGELOG.md`**.
 
 ```bash
 npm ci
@@ -401,4 +417,4 @@ npm run ci
 
 ## License
 
-Apache-2.0 (see `LICENSE` at the repository root and in the published npm package when released).
+Apache-2.0 (see **`LICENSE`** at the repository root).

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -26,13 +36,17 @@ __export(index_exports, {
   MemoryExporter: () => MemoryExporter,
   VERSION: () => VERSION,
   assertCorrelationId: () => assertCorrelationId,
+  assertValidExecutionEventWire: () => assertValidExecutionEventWire,
   assertWrapOptionsShape: () => assertWrapOptionsShape,
   client: () => client,
   createIntentProofClient: () => createIntentProofClient,
   getCorrelationId: () => getCorrelationId,
   getIntentProofClient: () => getIntentProofClient,
   runWithCorrelationId: () => runWithCorrelationId,
-  snapshot: () => snapshot
+  snapshot: () => snapshot,
+  validateExecutionEvent: () => validateExecutionEvent,
+  validateIntentProofConfig: () => validateIntentProofConfig,
+  validateWrapOptions: () => validateWrapOptions
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -164,8 +178,376 @@ function snapshot(value, options = {}) {
   }
 }
 
+// src/validators.ts
+var import__ = require("ajv/dist/2020.js");
+var AjvFormats = __toESM(require("ajv-formats"), 1);
+
+// src/generated/embed/execution-event.v1.ts
+var execution_event_v1_default = {
+  $comment: "Normative IntentProof source tree: https://github.com/IntentProof/intentproof-spec/tree/main/schema \u2014 $id is a logical URI; see README.",
+  $defs: {
+    ExecutionError: {
+      additionalProperties: false,
+      properties: {
+        cause: {
+          $ref: "#/$defs/ExecutionError",
+          description: "Optional chained cause; MUST conform to ExecutionError when present."
+        },
+        code: { description: "Optional stable machine-readable code.", type: "string" },
+        message: {
+          description: "Human-readable error message (may be empty string if the runtime provides none).",
+          type: "string"
+        },
+        name: {
+          description: "Exception or error type name (e.g. Error, TypeError).",
+          minLength: 1,
+          type: "string"
+        },
+        stack: {
+          description: "Optional stringified stack trace; null when stacks are suppressed.",
+          type: ["string", "null"]
+        }
+      },
+      required: ["name", "message"],
+      type: "object"
+    },
+    JsonValue: {
+      anyOf: [
+        { type: "null" },
+        { type: "boolean" },
+        { type: "number" },
+        { type: "string" },
+        { items: { $ref: "#/$defs/JsonValue" }, type: "array" },
+        { additionalProperties: { $ref: "#/$defs/JsonValue" }, type: "object" }
+      ],
+      description: "Any JSON-serializable value per semantics/serialization_rules.md."
+    }
+  },
+  $id: "https://intentproof.dev/schema/execution_event.v1.schema.json",
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  additionalProperties: false,
+  allOf: [
+    {
+      if: { properties: { status: { const: "ok" } }, required: ["status"] },
+      then: { not: { required: ["error"] }, required: ["output"] }
+    },
+    {
+      if: { properties: { status: { const: "error" } }, required: ["status"] },
+      then: { required: ["error"] }
+    }
+  ],
+  properties: {
+    action: {
+      description: "Stable identifier for the concrete operation. Many systems use hierarchical dotted names (e.g. vendor.resource.operation); REST paths, RPC names, or other conventions are allowed. The schema does not constrain the format.",
+      minLength: 1,
+      type: "string"
+    },
+    attributes: {
+      additionalProperties: { type: ["string", "number", "boolean", "null"] },
+      description: "Flat primitive key/value metadata attached to the event.",
+      propertyNames: { pattern: "^[A-Za-z0-9_.:-]{1,256}$" },
+      type: "object"
+    },
+    completedAt: {
+      description: "RFC 3339 / ISO 8601 instant when execution completed.",
+      format: "date-time",
+      type: "string"
+    },
+    correlationId: {
+      description: "Optional cross-cutting identifier for distributed tracing. MUST be trimmed and non-empty when present.",
+      minLength: 1,
+      type: "string"
+    },
+    durationMs: {
+      description: "Wall-clock duration in milliseconds between startedAt and completedAt.",
+      minimum: 0,
+      type: "number"
+    },
+    error: {
+      $ref: "#/$defs/ExecutionError",
+      description: "Structured error when status is error."
+    },
+    id: {
+      description: "Stable unique identifier for this execution record.",
+      minLength: 1,
+      type: "string"
+    },
+    inputs: {
+      additionalProperties: true,
+      description: "Captured call inputs. Values MUST be JSON-serializable (see semantics/serialization_rules.md).",
+      type: "object"
+    },
+    intent: {
+      description: "Natural-language description of what the user or caller was trying to achieve (often a full sentence or question). No fixed grammar; SHOULD stay human-readable in logs and UIs.",
+      minLength: 1,
+      type: "string"
+    },
+    output: {
+      $ref: "#/$defs/JsonValue",
+      description: "Captured return value when status is ok, or optional captured value when captureError allows output on failure."
+    },
+    startedAt: {
+      description: "RFC 3339 / ISO 8601 instant when execution started.",
+      format: "date-time",
+      type: "string"
+    },
+    status: {
+      description: "Terminal execution status.",
+      enum: ["ok", "error"],
+      type: "string"
+    }
+  },
+  required: [
+    "id",
+    "intent",
+    "action",
+    "status",
+    "inputs",
+    "startedAt",
+    "completedAt",
+    "durationMs"
+  ],
+  title: "IntentProof ExecutionEvent v1",
+  type: "object"
+};
+
+// src/generated/embed/intentproof-config.v1.ts
+var intentproof_config_v1_default = {
+  $comment: "Normative IntentProof source tree: https://github.com/IntentProof/intentproof-spec/tree/main/schema \u2014 $id is a logical URI; see README.",
+  $defs: {
+    WrapOptionsV1: {
+      $comment: "Normative IntentProof source tree: https://github.com/IntentProof/intentproof-spec/tree/main/schema \u2014 $id is a logical URI; see README.",
+      $id: "https://intentproof.dev/schema/wrap_options.v1.schema.json",
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      additionalProperties: false,
+      properties: {
+        action: {
+          description: "Default operation identifier (often dotted like vendor.service.method); SDKs MAY derive from the callable when omitted.",
+          minLength: 1,
+          type: "string"
+        },
+        attributes: {
+          additionalProperties: { type: ["string", "number", "boolean", "null"] },
+          description: "Static attributes merged into each emitted ExecutionEvent.attributes.",
+          type: "object"
+        },
+        captureError: {
+          default: true,
+          description: "When true, failures MUST populate error; when false with captureOutput semantics, see semantics/wrap_behavior.md.",
+          type: "boolean"
+        },
+        captureInputs: {
+          default: true,
+          description: "When false, inputs MUST be serialized as an empty object {}.",
+          type: "boolean"
+        },
+        captureOutput: {
+          default: true,
+          description: "When false and status is ok, output MUST be null.",
+          type: "boolean"
+        },
+        captureStack: {
+          default: true,
+          description: "When false, error.stack MUST be null on emitted events.",
+          type: "boolean"
+        },
+        exporterTimeoutMs: {
+          description: "Maximum time an exporter hook may block the wrap boundary; 0 means SDK default.",
+          minimum: 0,
+          type: "number"
+        },
+        intent: {
+          description: "Default natural-language intent for wrapped executions when the call site does not override it.",
+          minLength: 1,
+          type: "string"
+        },
+        propagateCorrelation: {
+          default: true,
+          description: "When true, nested wraps inherit the active correlationId.",
+          type: "boolean"
+        }
+      },
+      title: "IntentProof WrapOptions v1",
+      type: "object"
+    }
+  },
+  $id: "https://intentproof.dev/schema/intentproof_config.v1.schema.json",
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  additionalProperties: false,
+  properties: {
+    correlation: {
+      additionalProperties: false,
+      properties: {
+        generateOnMissing: {
+          default: true,
+          description: "When true, SDK generates a UUID when no correlation is active.",
+          type: "boolean"
+        },
+        headerName: {
+          default: "x-intentproof-correlation-id",
+          description: "HTTP header used for inbound correlation extraction when applicable.",
+          type: "string"
+        }
+      },
+      type: "object"
+    },
+    defaultWrapOptions: { $ref: "#/$defs/WrapOptionsV1" },
+    exporters: {
+      description: "Ordered list of exporter identifiers or inline hooks (SDK-defined encoding).",
+      items: {
+        additionalProperties: true,
+        properties: {
+          endpoint: {
+            description: "Required for http exporters when used.",
+            format: "uri",
+            type: "string"
+          },
+          failOpen: {
+            default: true,
+            description: "When true, exporter failures MUST NOT change user-visible outcomes.",
+            type: "boolean"
+          },
+          headers: {
+            additionalProperties: { type: "string" },
+            description: "Optional HTTP headers for http exporters.",
+            type: "object"
+          },
+          type: {
+            description: "Exporter kind; custom MUST include implementation-specific fields.",
+            enum: ["console", "http", "otel", "custom"],
+            type: "string"
+          }
+        },
+        required: ["type"],
+        type: "object"
+      },
+      type: "array"
+    },
+    serialization: {
+      additionalProperties: false,
+      properties: {
+        maxDepth: {
+          default: 32,
+          description: "Maximum object graph depth for input/output capture.",
+          minimum: 1,
+          type: "integer"
+        },
+        maxStringLength: {
+          default: 65536,
+          description: "Maximum serialized string length for any single field.",
+          minimum: 1,
+          type: "integer"
+        },
+        redactKeys: {
+          description: "Case-insensitive key names to replace with [REDACTED] in captured objects.",
+          items: { type: "string" },
+          type: "array"
+        }
+      },
+      type: "object"
+    },
+    version: {
+      const: 1,
+      description: "Config document version; MUST be 1 for this schema.",
+      type: "integer"
+    }
+  },
+  title: "IntentProof Runtime Config v1",
+  type: "object"
+};
+
+// src/generated/embed/wrap-options.v1.ts
+var wrap_options_v1_default = {
+  $comment: "Normative IntentProof source tree: https://github.com/IntentProof/intentproof-spec/tree/main/schema \u2014 $id is a logical URI; see README.",
+  $id: "https://intentproof.dev/schema/wrap_options.v1.schema.json",
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  additionalProperties: false,
+  properties: {
+    action: {
+      description: "Default operation identifier (often dotted like vendor.service.method); SDKs MAY derive from the callable when omitted.",
+      minLength: 1,
+      type: "string"
+    },
+    attributes: {
+      additionalProperties: { type: ["string", "number", "boolean", "null"] },
+      description: "Static attributes merged into each emitted ExecutionEvent.attributes.",
+      type: "object"
+    },
+    captureError: {
+      default: true,
+      description: "When true, failures MUST populate error; when false with captureOutput semantics, see semantics/wrap_behavior.md.",
+      type: "boolean"
+    },
+    captureInputs: {
+      default: true,
+      description: "When false, inputs MUST be serialized as an empty object {}.",
+      type: "boolean"
+    },
+    captureOutput: {
+      default: true,
+      description: "When false and status is ok, output MUST be null.",
+      type: "boolean"
+    },
+    captureStack: {
+      default: true,
+      description: "When false, error.stack MUST be null on emitted events.",
+      type: "boolean"
+    },
+    exporterTimeoutMs: {
+      description: "Maximum time an exporter hook may block the wrap boundary; 0 means SDK default.",
+      minimum: 0,
+      type: "number"
+    },
+    intent: {
+      description: "Default natural-language intent for wrapped executions when the call site does not override it.",
+      minLength: 1,
+      type: "string"
+    },
+    propagateCorrelation: {
+      default: true,
+      description: "When true, nested wraps inherit the active correlationId.",
+      type: "boolean"
+    }
+  },
+  title: "IntentProof WrapOptions v1",
+  type: "object"
+};
+
+// src/validators.ts
+var ajv = new import__.Ajv2020({
+  allErrors: true,
+  strict: false
+});
+var addFormats = AjvFormats.default;
+addFormats(ajv);
+var validateExecutionEvent = ajv.compile(
+  execution_event_v1_default
+);
+var validateWrapOptions = ajv.compile(
+  wrap_options_v1_default
+);
+var validateIntentProofConfig = ajv.compile(
+  intentproof_config_v1_default
+);
+function errorsText(v) {
+  return ajv.errorsText(v.errors, { separator: "; " });
+}
+function assertValidExecutionEventWire(data) {
+  if (!validateExecutionEvent(data)) {
+    throw new TypeError(
+      `ExecutionEvent wire JSON failed schema validation: ${errorsText(validateExecutionEvent)}`
+    );
+  }
+}
+
 // src/client.ts
 var correlationStore = new import_async_hooks.AsyncLocalStorage();
+function normalizeInputsForExecutionEvent(inputs) {
+  if (inputs !== null && typeof inputs === "object" && !Array.isArray(inputs)) {
+    return inputs;
+  }
+  return { args: inputs };
+}
 function assertCorrelationId(id) {
   if (typeof id !== "string") {
     throw new TypeError(
@@ -191,7 +573,8 @@ function runWithCorrelationId(correlationId, fn) {
   return correlationStore.run(correlationId, fn);
 }
 function defaultOnExporterError(error, _event) {
-  console.error("[intentproof] exporter error", error);
+  const message = error instanceof Error ? error.message : String(error);
+  console.error("[intentproof] exporter error", message);
 }
 function toErrorSnapshot(e, includeStack) {
   if (e instanceof Error) {
@@ -390,9 +773,12 @@ var IntentProofClient = class {
         correlationId,
         intent: options.intent,
         action: options.action,
-        inputs,
+        inputs: normalizeInputsForExecutionEvent(inputs),
         startedAt: startedAt.toISOString(),
-        attributes: mergeAttrs(self.defaultAttributes, options.attributes)
+        attributes: mergeAttrs(
+          self.defaultAttributes,
+          options.attributes
+        )
       };
       try {
         const out = fn.apply(this, args);
@@ -500,6 +886,7 @@ var IntentProofClient = class {
     this.dispatch(event);
   }
   dispatch(event) {
+    assertValidExecutionEventWire(JSON.parse(JSON.stringify(event)));
     for (const ex of this.exporters) {
       try {
         const r = ex.export(event);
@@ -757,7 +1144,7 @@ var BoundedQueueExporter = class {
 };
 
 // src/index.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.4";
 var client = getIntentProofClient();
 function createIntentProofClient(config) {
   return new IntentProofClient(config);
@@ -770,12 +1157,16 @@ function createIntentProofClient(config) {
   MemoryExporter,
   VERSION,
   assertCorrelationId,
+  assertValidExecutionEventWire,
   assertWrapOptionsShape,
   client,
   createIntentProofClient,
   getCorrelationId,
   getIntentProofClient,
   runWithCorrelationId,
-  snapshot
+  snapshot,
+  validateExecutionEvent,
+  validateIntentProofConfig,
+  validateWrapOptions
 });
 //# sourceMappingURL=index.cjs.map