@kindgi/audit-events 0.1.4-rc.0 → 0.1.4-rc.2

package/README.md

@@ -16,10 +16,10 @@ Give the whole system one audit substrate: one record shape, one write surface,
   - `payload` — versioned envelope `{ v: 1, doc: … }`; the `doc` shape depends on `kind`.
 - **`AuditEventBinding`** — the adapter interface:
   - `append(events)` — batched write. Duplicate `(tenantId, id)` pairs are ignored, so retries are safe. Fails with `PersistenceError` or `AuditEventValidationError`.
-  - `query(input)` — cursor-paginated read ordered by `(timestamp, id)`; the cursor is opaque. Fails with `PersistenceError` or `InvalidCursorError`.
+  - `query(input)` — cursor-paginated read ordered by `(timestamp, id)`, oldest first, or newest first with `order: 'desc'`; the cursor is opaque and continues in the same order. Fails with `PersistenceError` or `InvalidCursorError`.
   - `purge(input)` — delete one kind's events older than a cutoff; returns the deleted count.
   - `describe()` — `{ name, version }`.
-- **`AuditEventQueryInput`** — `tenantId`, `filter?`, `cursor?`, `limit?`.
+- **`AuditEventQueryInput`** — `tenantId`, `filter?`, `cursor?`, `limit?`, `order?` (**`AuditEventOrder`**: `'asc'`, the default, or `'desc'`). A binding that predates `order` pages oldest first.
 - **`AuditEventFilter`** — AND-combined; absent fields match anything. Fields: `id`, `kind`, `kinds` (an empty array matches nothing), `actor`, `onBehalfOf`, `runId`, `agentId`, `flowId`, `correlationId`, `outcome`, `payloadDoc` (every entry must equal the same field of `payload.doc`), and inclusive ISO `from` / `to` bounds.
 - **`AuditEventPage`** — `data` plus `nextCursor` (absent on the last page).
 - **`AuditEventPurgeInput`** (`tenantId`, `kind`, `olderThan`) and **`AuditEventPurgeResult`** (`deleted`).

package/dist/binding.d.ts

@@ -11,7 +11,8 @@ import type { AuditEvent, AuditEventFilter, AuditEventPage } from './types.js';
  *     (idempotent — safer than throwing when the caller re-fires
  *     from a retry loop).
  *   - `query` — cursor-paginated read; opaque cursor tokens encode
- *     `(timestamp, id)` for keyset pagination.
+ *     `(timestamp, id)` for keyset pagination, oldest first or, with
+ *     `order: 'desc'`, newest first.
  *   - `purge` — delete rows matching `(tenantId, kind, olderThan)`;
  *     retention cleanup calls this per kind. Legal-hold kinds are
  *     excluded by the caller (the compliance classifier decides).
@@ -34,7 +35,15 @@ export interface AuditEventQueryInput {
     readonly filter?: AuditEventFilter;
     readonly cursor?: string;
     readonly limit?: number;
+    /**
+     * `asc` (absent): oldest first. `desc`: newest first. `nextCursor`
+     * continues in the same order. A binding that predates `order` pages
+     * oldest first.
+     */
+    readonly order?: AuditEventOrder;
 }
+/** The order `query` pages in, by `(timestamp, id)`. */
+export type AuditEventOrder = 'asc' | 'desc';
 export interface AuditEventPurgeInput {
     readonly tenantId: TenantId;
     /**
@@ -45,6 +54,13 @@ export interface AuditEventPurgeInput {
     readonly kind: string;
     /** ISO timestamp cutoff. Rows with `timestamp < olderThan` are deleted. */
     readonly olderThan: string;
+    /**
+     * Only rows with this outcome, e.g. a kind's denials kept longer than the
+     * rest (a classifier's `onDenyDays`). Absent: any outcome.
+     */
+    readonly outcome?: string;
+    /** Only rows whose outcome isn't this one (rows with no outcome included). */
+    readonly exceptOutcome?: string;
 }
 export interface AuditEventPurgeResult {
     readonly deleted: number;

package/dist/binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CACJ,MAAM,EAAE,SAAS,UAAU,EAAE,GAC5B,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,yBAAyB,CAAC,CAAC,CAAC;IAEvE,KAAK,CACH,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,GAAG,kBAAkB,CAAC,CAAC,CAAC;IAE1E,KAAK,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAE7F,QAAQ,IAAI;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CACJ,MAAM,EAAE,SAAS,UAAU,EAAE,GAC5B,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,yBAAyB,CAAC,CAAC,CAAC;IAEvE,KAAK,CACH,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,GAAG,kBAAkB,CAAC,CAAC,CAAC;IAE1E,KAAK,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAE7F,QAAQ,IAAI;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { AuditEventBinding, AuditEventPurgeInput, AuditEventPurgeResult, AuditEventQueryInput, } from './binding.js';
+export type { AuditEventBinding, AuditEventOrder, AuditEventPurgeInput, AuditEventPurgeResult, AuditEventQueryInput, } from './binding.js';
 export type { AuditEventError, AuditEventValidationError, InvalidCursorError, PersistenceError, } from './errors.js';
 export type { AuditEvent, AuditEventFilter, AuditEventPage } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/audit-events",
-  "version": "0.1.4-rc.0",
+  "version": "0.1.4-rc.2",
   "description": "Kindgi™ audit events contract. Types only: AuditEvent (the audit record — id, tenantId, projectId, kind, timestamp, actor, outcome, run / agent / flow / correlation ids, versioned payload), AuditEventFilter and AuditEventPage, AuditEventBinding (the caller-plugged append / query / purge interface) with its input and result shapes, and the AuditEventError union. No runtime code. A reference in-memory binding is @kindgi/audit-events-inmemory; durable bindings are provided by the Kindgi runtime.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/types": "0.1.4-rc.0"
+    "@kindgi/types": "0.1.4-rc.2"
   },
   "engines": {
     "node": ">=22.12.0"

package/src/binding.ts

@@ -16,7 +16,8 @@ import type { AuditEvent, AuditEventFilter, AuditEventPage } from './types.js';
  *     (idempotent — safer than throwing when the caller re-fires
  *     from a retry loop).
  *   - `query` — cursor-paginated read; opaque cursor tokens encode
- *     `(timestamp, id)` for keyset pagination.
+ *     `(timestamp, id)` for keyset pagination, oldest first or, with
+ *     `order: 'desc'`, newest first.
  *   - `purge` — delete rows matching `(tenantId, kind, olderThan)`;
  *     retention cleanup calls this per kind. Legal-hold kinds are
  *     excluded by the caller (the compliance classifier decides).
@@ -44,8 +45,17 @@ export interface AuditEventQueryInput {
   readonly filter?: AuditEventFilter;
   readonly cursor?: string;
   readonly limit?: number;
+  /**
+   * `asc` (absent): oldest first. `desc`: newest first. `nextCursor`
+   * continues in the same order. A binding that predates `order` pages
+   * oldest first.
+   */
+  readonly order?: AuditEventOrder;
 }
 
+/** The order `query` pages in, by `(timestamp, id)`. */
+export type AuditEventOrder = 'asc' | 'desc';
+
 export interface AuditEventPurgeInput {
   readonly tenantId: TenantId;
   /**
@@ -56,6 +66,13 @@ export interface AuditEventPurgeInput {
   readonly kind: string;
   /** ISO timestamp cutoff. Rows with `timestamp < olderThan` are deleted. */
   readonly olderThan: string;
+  /**
+   * Only rows with this outcome, e.g. a kind's denials kept longer than the
+   * rest (a classifier's `onDenyDays`). Absent: any outcome.
+   */
+  readonly outcome?: string;
+  /** Only rows whose outcome isn't this one (rows with no outcome included). */
+  readonly exceptOutcome?: string;
 }
 
 export interface AuditEventPurgeResult {

package/src/index.ts

@@ -3,6 +3,7 @@
 
 export type {
   AuditEventBinding,
+  AuditEventOrder,
   AuditEventPurgeInput,
   AuditEventPurgeResult,
   AuditEventQueryInput,