@xyo-network/event-kit-statement-graph 0.0.1

package/README.md

@@ -0,0 +1,59 @@
+# `@xyo-network/event-kit-statement-graph`
+
+Read-model adapter between the canonical XL1 Statement Graph viewer and the
+Event Kit wake-grant authorizer.
+
+```ts
+const readModel = createStatementGraphGrantReadModel({ viewer })
+const grants = createStatementGraphWakeGrantAuthorizer({ viewer: readModel })
+```
+
+`viewer` is any `StatementGraphViewer` — a `StateStatementGraphViewer` over
+engine state, a replay controller's viewer, or another backing.
+
+## What this package does and does not do
+
+It is a translation seam only. It narrows the canonical branded source/hash
+types, preserves every field the authorizer needs as grant evidence, and drops
+nothing. It makes no authorization decision and applies no freshness policy.
+
+Under Statement Graph v2 the protocol owns **claim only**: there is no `target`
+and no revoke verb, so the grant body names its own `publisher` and negation is
+an Event Kit revocation object claimed by the pinned controller. See
+[D-003](../../docs/decisions/D-003-STATEMENT-GRAPH-V2-GRANTS.md).
+
+Addresses and hashes are **parsed**, not cast. A malformed address therefore
+reaches the caller as `grant-unavailable` rather than silently querying a
+nonsense key and reading as "no grant".
+
+## Evidence
+
+Specs fold a `FakeStatementChain` through the real engine —
+`applyStatementTransaction` over decoded blocks and verified bodies — and drive
+`admitAndEnqueue` against the resulting viewer. Exact-scope claims admit; a
+wrong controller, a differently scoped or unscoped route, a missing `enqueue`
+permission, and a revoke all reject; a lagging view rejects as stale and an
+ahead-of-finality view rejects rather than being trusted.
+
+A never-folded read model carries watermark `-1` and fails closed as
+`grant-unavailable`, keeping "the view is not ready" distinguishable from "the
+controller granted nothing".
+
+Live specs under `src/spec/api-local/` run the same fold against a **real local
+XL1 chain**: a Claim transaction published with the statement-graph SDK,
+confirmed and finalized, then folded from real finalized blocks into an
+admission decision whose evidence cites the on-chain claim at its real height.
+The gateway viewer satisfies `FinalizedBlockViewer` structurally, so the fold
+code is identical across both substrates. Run with
+`pnpm test:api-local-statements` — publishing specs need their own chain, since
+the dev chain stops producing blocks after one statement transaction.
+
+The full lifecycle runs live: a grant admits, a negation in a **later** finalized
+transaction disables, and a later redundant claim leaves the asserted height
+frozen while only the liveness clock advances. Same-block negation is covered too
+via v2's `hashes[]` fan-out, where a grant and the revocation naming it ride one
+transaction and the publisher is born disabled.
+
+Bodies are served from an in-process datalake; the chain carries commitments, not
+bodies. Scope-mismatch and wrong-controller vectors stay on the deterministic
+chain.

package/dist/neutral/grantReadModel.d.ts

@@ -0,0 +1,21 @@
+import type { StatementGraphGrantReadModel } from '@xyo-network/event-kit-protocol';
+import type { StatementGraphViewer } from '@xyo-network/xl1-statement-graph-engine';
+export interface StatementGraphGrantReadModelOptions {
+    /**
+     * Canonical Statement Graph read surface — a `StateStatementGraphViewer` over
+     * engine state, a replay controller's viewer, or any other backing.
+     */
+    readonly viewer: StatementGraphViewer;
+}
+/**
+ * Adapts the canonical Statement Graph v2 viewer to the unbranded read model
+ * the Event Kit grant authorizer consumes.
+ *
+ * This is a translation seam only. It narrows branded query and record types
+ * and preserves every field the authorizer needs as grant evidence; it makes no
+ * authorization decision, applies no freshness policy, and drops no claim.
+ * Statement Graph remains the sole owner of claim semantics — and under v2 that
+ * is the whole lifecycle, since there is no revoke verb to own.
+ */
+export declare function createStatementGraphGrantReadModel(options: StatementGraphGrantReadModelOptions): StatementGraphGrantReadModel;
+//# sourceMappingURL=grantReadModel.d.ts.map

package/dist/neutral/grantReadModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grantReadModel.d.ts","sourceRoot":"","sources":["../../src/grantReadModel.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAIV,4BAA4B,EAC7B,MAAM,iCAAiC,CAAA;AAExC,OAAO,KAAK,EAEV,oBAAoB,EACrB,MAAM,yCAAyC,CAAA;AAGhD,MAAM,WAAW,mCAAmC;IAClD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CACtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,mCAAmC,GAC3C,4BAA4B,CAqB9B"}

package/dist/neutral/index.d.ts

@@ -0,0 +1,3 @@
+export type { StatementGraphGrantReadModelOptions } from './grantReadModel.ts';
+export { createStatementGraphGrantReadModel } from './grantReadModel.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/neutral/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAA;AAC9E,OAAO,EAAE,kCAAkC,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/neutral/index.mjs

@@ -0,0 +1,48 @@
+// src/grantReadModel.ts
+import { HashZod } from "@ariestools/sdk";
+import { XyoAddressZod } from "@xyo-network/sdk-protocol/address";
+function createStatementGraphGrantReadModel(options) {
+  const { viewer } = options;
+  return Object.freeze({
+    async head() {
+      return await viewer.head();
+    },
+    async claims(source, query) {
+      const records = await viewer.claims(XyoAddressZod.parse(source), toClaimQuery(query));
+      return Object.freeze(records.map(toGrantClaim));
+    },
+    async object(objectHash) {
+      const record = await viewer.object(HashZod.parse(objectHash));
+      return record === void 0 ? void 0 : toGrantObject(record);
+    }
+  });
+}
+function toClaimQuery(query) {
+  if (query === void 0) return void 0;
+  return {
+    ...query.declaredObjectSchemaPrefix === void 0 ? {} : { declaredObjectSchemaPrefix: query.declaredObjectSchemaPrefix },
+    ...query.objectHash === void 0 ? {} : { objectHash: HashZod.parse(query.objectHash) }
+  };
+}
+function toGrantClaim(record) {
+  return Object.freeze({
+    declaredObjectSchema: record.declaredObjectSchema,
+    firstBlock: record.firstBlock,
+    firstEventHash: record.firstEventHash,
+    lastBlock: record.lastBlock,
+    objectHash: record.objectHash,
+    source: record.source
+  });
+}
+function toGrantObject(record) {
+  return Object.freeze({
+    assurance: record.assurance,
+    declaredSchema: record.declaredSchema,
+    objectHash: record.objectHash,
+    params: record.params === null ? null : Object.freeze({ ...record.params })
+  });
+}
+export {
+  createStatementGraphGrantReadModel
+};
+//# sourceMappingURL=index.mjs.map

package/dist/neutral/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/grantReadModel.ts"],
+  "sourcesContent": ["import { HashZod } from '@ariestools/sdk'\nimport type {\n  StatementGrantClaim,\n  StatementGrantClaimQuery,\n  StatementGrantObject,\n  StatementGraphGrantReadModel,\n} from '@xyo-network/event-kit-protocol'\nimport { XyoAddressZod } from '@xyo-network/sdk-protocol/address'\nimport type {\n  ClaimQuery,\n  StatementGraphViewer,\n} from '@xyo-network/xl1-statement-graph-engine'\nimport type { ClaimRecord, ObjectRecord } from '@xyo-network/xl1-statement-graph-schemas'\n\nexport interface StatementGraphGrantReadModelOptions {\n  /**\n   * Canonical Statement Graph read surface \u2014 a `StateStatementGraphViewer` over\n   * engine state, a replay controller's viewer, or any other backing.\n   */\n  readonly viewer: StatementGraphViewer\n}\n\n/**\n * Adapts the canonical Statement Graph v2 viewer to the unbranded read model\n * the Event Kit grant authorizer consumes.\n *\n * This is a translation seam only. It narrows branded query and record types\n * and preserves every field the authorizer needs as grant evidence; it makes no\n * authorization decision, applies no freshness policy, and drops no claim.\n * Statement Graph remains the sole owner of claim semantics \u2014 and under v2 that\n * is the whole lifecycle, since there is no revoke verb to own.\n */\nexport function createStatementGraphGrantReadModel(\n  options: StatementGraphGrantReadModelOptions,\n): StatementGraphGrantReadModel {\n  const { viewer } = options\n\n  return Object.freeze({\n    async head(): Promise<number> {\n      return await viewer.head()\n    },\n\n    async claims(\n      source: string,\n      query?: StatementGrantClaimQuery,\n    ): Promise<readonly StatementGrantClaim[]> {\n      const records = await viewer.claims(XyoAddressZod.parse(source), toClaimQuery(query))\n      return Object.freeze(records.map(toGrantClaim))\n    },\n\n    async object(objectHash: string): Promise<StatementGrantObject | undefined> {\n      const record = await viewer.object(HashZod.parse(objectHash))\n      return record === undefined ? undefined : toGrantObject(record)\n    },\n  })\n}\n\n/**\n * Rebrands the query fields. Parsing rather than casting means a malformed hash\n * reaches the viewer as a throw \u2014 surfacing as `grant-unavailable` \u2014 instead of\n * silently querying a nonsense key and reading as \"no grant\".\n */\nfunction toClaimQuery(query?: StatementGrantClaimQuery): ClaimQuery | undefined {\n  if (query === undefined) return undefined\n  return {\n    ...(query.declaredObjectSchemaPrefix === undefined\n      ? {}\n      : { declaredObjectSchemaPrefix: query.declaredObjectSchemaPrefix }),\n    ...(query.objectHash === undefined ? {} : { objectHash: HashZod.parse(query.objectHash) }),\n  }\n}\n\n/**\n * `firstEventHash` identifies the materializing claim, so the authorizer can\n * cite one concrete transition as evidence rather than a bare boolean. A\n * redundant claim moves only `lastBlock`, so evidence cannot be backdated or\n * refreshed by re-claiming.\n */\nfunction toGrantClaim(record: ClaimRecord): StatementGrantClaim {\n  return Object.freeze({\n    declaredObjectSchema: record.declaredObjectSchema,\n    firstBlock: record.firstBlock,\n    firstEventHash: record.firstEventHash,\n    lastBlock: record.lastBlock,\n    objectHash: record.objectHash,\n    source: record.source,\n  })\n}\n\nfunction toGrantObject(record: ObjectRecord): StatementGrantObject {\n  return Object.freeze({\n    assurance: record.assurance,\n    declaredSchema: record.declaredSchema,\n    objectHash: record.objectHash,\n    params: record.params === null ? null : Object.freeze({ ...record.params }),\n  })\n}\n"],
+  "mappings": ";AAAA,SAAS,eAAe;AAOxB,SAAS,qBAAqB;AAyBvB,SAAS,mCACd,SAC8B;AAC9B,QAAM,EAAE,OAAO,IAAI;AAEnB,SAAO,OAAO,OAAO;AAAA,IACnB,MAAM,OAAwB;AAC5B,aAAO,MAAM,OAAO,KAAK;AAAA,IAC3B;AAAA,IAEA,MAAM,OACJ,QACA,OACyC;AACzC,YAAM,UAAU,MAAM,OAAO,OAAO,cAAc,MAAM,MAAM,GAAG,aAAa,KAAK,CAAC;AACpF,aAAO,OAAO,OAAO,QAAQ,IAAI,YAAY,CAAC;AAAA,IAChD;AAAA,IAEA,MAAM,OAAO,YAA+D;AAC1E,YAAM,SAAS,MAAM,OAAO,OAAO,QAAQ,MAAM,UAAU,CAAC;AAC5D,aAAO,WAAW,SAAY,SAAY,cAAc,MAAM;AAAA,IAChE;AAAA,EACF,CAAC;AACH;AAOA,SAAS,aAAa,OAA0D;AAC9E,MAAI,UAAU,OAAW,QAAO;AAChC,SAAO;AAAA,IACL,GAAI,MAAM,+BAA+B,SACrC,CAAC,IACD,EAAE,4BAA4B,MAAM,2BAA2B;AAAA,IACnE,GAAI,MAAM,eAAe,SAAY,CAAC,IAAI,EAAE,YAAY,QAAQ,MAAM,MAAM,UAAU,EAAE;AAAA,EAC1F;AACF;AAQA,SAAS,aAAa,QAA0C;AAC9D,SAAO,OAAO,OAAO;AAAA,IACnB,sBAAsB,OAAO;AAAA,IAC7B,YAAY,OAAO;AAAA,IACnB,gBAAgB,OAAO;AAAA,IACvB,WAAW,OAAO;AAAA,IAClB,YAAY,OAAO;AAAA,IACnB,QAAQ,OAAO;AAAA,EACjB,CAAC;AACH;AAEA,SAAS,cAAc,QAA4C;AACjE,SAAO,OAAO,OAAO;AAAA,IACnB,WAAW,OAAO;AAAA,IAClB,gBAAgB,OAAO;AAAA,IACvB,YAAY,OAAO;AAAA,IACnB,QAAQ,OAAO,WAAW,OAAO,OAAO,OAAO,OAAO,EAAE,GAAG,OAAO,OAAO,CAAC;AAAA,EAC5E,CAAC;AACH;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@xyo-network/event-kit-statement-graph",
+  "version": "0.0.1",
+  "description": "Statement Graph read-model adapter for Event Kit wake grants",
+  "keywords": [
+    "xyo",
+    "xl1",
+    "event-kit",
+    "statement-graph",
+    "typescript"
+  ],
+  "bugs": {
+    "url": "https://github.com/XYOracleNetwork/event-kit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XYOracleNetwork/event-kit.git",
+    "directory": "packages/statement-graph"
+  },
+  "license": "UNLICENSED",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/neutral/index.d.ts",
+      "default": "./dist/neutral/index.mjs"
+    },
+    "./package.json": "./package.json",
+    "./README.md": "./README.md"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@xyo-network/event-kit-protocol": "~0.0.1"
+  },
+  "devDependencies": {
+    "@ariestools/lib-neutral": "~9.1.0",
+    "@ariestools/sdk": "~8.1.9",
+    "@ariestools/toolchain": "~9.1.0",
+    "@ariestools/tsconfig": "~9.1.0",
+    "@opentelemetry/api": "~1.9.1",
+    "@xyo-network/sdk": "~7.2.3",
+    "@xyo-network/sdk-protocol": "~7.2.4",
+    "@xyo-network/xl1-sdk": "~5.3.1",
+    "@xyo-network/xl1-statement-graph-engine": "~0.4.0",
+    "@xyo-network/xl1-statement-graph-schemas": "~0.4.0",
+    "@xyo-network/xl1-statement-graph-sdk": "~0.4.0",
+    "@xyo-network/xl1-statement-graph-testing": "~0.4.0",
+    "async-mutex": "~0.5.0",
+    "eslint": "~10.8.1",
+    "eslint-import-resolver-typescript": "~4.4.5",
+    "ethers": "~6.17.0",
+    "typescript": "~6.0.3",
+    "vite": "~8.2.1",
+    "vitest": "~4.1.11",
+    "zod": "~4.4.3",
+    "@xyo-network/event-kit-schemas": "~0.0.1"
+  },
+  "peerDependencies": {
+    "@ariestools/sdk": "^8.1",
+    "@opentelemetry/api": "^1.9",
+    "@xyo-network/sdk": "^7.2",
+    "@xyo-network/sdk-protocol": "^7.2",
+    "@xyo-network/xl1-statement-graph-engine": "^0.4",
+    "zod": "^4.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}