@agenticprimitives/situations 0.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @agenticprimitives/situations
+
+Substrate `SituationV2` types and validators (spec 324). A Situation is the state of affairs; a credential attests it.

package/dist/canonical.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RFC 8785 JSON Canonicalization Scheme (JCS) — deterministic JSON serialisation
+ * for cross-stack hash equality (TS ↔ Solidity ↔ Java/Go verifiers).
+ *
+ * The substrate's `credentialHash` is `keccak256(jcsCanonicalize(vc-without-proof))`.
+ * Every package that needs to recompute the hash MUST go through this helper.
+ *
+ * RFC 8785 rules:
+ *  - UTF-8 strings, NFC normalisation (browsers ship NFC already)
+ *  - Object keys sorted by UTF-16 code unit (== lexicographic in BMP)
+ *  - No insignificant whitespace
+ *  - Numbers as the shortest IEEE 754 round-trip representation
+ *  - Booleans `true` / `false` / `null` lowercase
+ *  - Strings JSON-escape U+0000..U+001F, U+0022, U+005C only; emit other code points as-is
+ *
+ * This implementation is intentionally narrow: substrate VCs use a constrained
+ * subset of JSON (string / number / boolean / null / object / array). We do not
+ * handle BigInt or Date — callers must serialise those upstream.
+ */
+export declare class JcsError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Canonicalize a JSON-compatible value per RFC 8785.
+ * Returns the canonical string (UTF-8 text; callers wrap with `utf8ToBytes` to hash).
+ */
+export declare function jcsCanonicalize(value: unknown, path?: string): string;
+/**
+ * Compute the canonical hash of a value: `keccak256(jcsCanonicalize(value))`.
+ * Returns the 32-byte hex hash.
+ */
+export declare function canonicalHash(value: unknown): `0x${string}`;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,qBAAa,QAAS,SAAQ,KAAK;IACJ,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAtC,OAAO,EAAE,MAAM,EAAW,IAAI,EAAE,MAAM;CAGnD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,MAAY,GAAG,MAAM,CA2B1E;AAkED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,MAAM,EAAE,CAK3D"}

package/dist/canonical.js

@@ -0,0 +1,146 @@
+/**
+ * RFC 8785 JSON Canonicalization Scheme (JCS) — deterministic JSON serialisation
+ * for cross-stack hash equality (TS ↔ Solidity ↔ Java/Go verifiers).
+ *
+ * The substrate's `credentialHash` is `keccak256(jcsCanonicalize(vc-without-proof))`.
+ * Every package that needs to recompute the hash MUST go through this helper.
+ *
+ * RFC 8785 rules:
+ *  - UTF-8 strings, NFC normalisation (browsers ship NFC already)
+ *  - Object keys sorted by UTF-16 code unit (== lexicographic in BMP)
+ *  - No insignificant whitespace
+ *  - Numbers as the shortest IEEE 754 round-trip representation
+ *  - Booleans `true` / `false` / `null` lowercase
+ *  - Strings JSON-escape U+0000..U+001F, U+0022, U+005C only; emit other code points as-is
+ *
+ * This implementation is intentionally narrow: substrate VCs use a constrained
+ * subset of JSON (string / number / boolean / null / object / array). We do not
+ * handle BigInt or Date — callers must serialise those upstream.
+ */
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { utf8ToBytes } from '@noble/hashes/utils.js';
+export class JcsError extends Error {
+    path;
+    constructor(message, path) {
+        super(`[JCS] ${message} at ${path}`);
+        this.path = path;
+    }
+}
+/**
+ * Canonicalize a JSON-compatible value per RFC 8785.
+ * Returns the canonical string (UTF-8 text; callers wrap with `utf8ToBytes` to hash).
+ */
+export function jcsCanonicalize(value, path = '$') {
+    if (value === null)
+        return 'null';
+    if (value === undefined) {
+        throw new JcsError('undefined is not JSON', path);
+    }
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'string':
+            return serializeString(value);
+        case 'number':
+            return serializeNumber(value, path);
+        case 'object': {
+            if (Array.isArray(value)) {
+                const items = value.map((v, i) => jcsCanonicalize(v, `${path}[${i}]`));
+                return `[${items.join(',')}]`;
+            }
+            // Plain object
+            const entries = Object.entries(value)
+                .filter(([, v]) => v !== undefined)
+                .sort(([a], [b]) => sortByCodeUnit(a, b));
+            const items = entries.map(([k, v]) => `${serializeString(k)}:${jcsCanonicalize(v, `${path}.${k}`)}`);
+            return `{${items.join(',')}}`;
+        }
+        default:
+            throw new JcsError(`unsupported JSON type: ${typeof value}`, path);
+    }
+}
+/** UTF-16 code unit comparison — exactly what RFC 8785 §3.2.3 requires. */
+function sortByCodeUnit(a, b) {
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const av = a.charCodeAt(i);
+        const bv = b.charCodeAt(i);
+        if (av !== bv)
+            return av - bv;
+    }
+    return a.length - b.length;
+}
+/** RFC 8259 string serialisation with JCS-compatible escaping (RFC 8785 §3.2.2.2). */
+function serializeString(s) {
+    let out = '"';
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        if (code === 0x22) {
+            out += '\\"';
+        }
+        else if (code === 0x5c) {
+            out += '\\\\';
+        }
+        else if (code < 0x20) {
+            // Control characters
+            switch (code) {
+                case 0x08:
+                    out += '\\b';
+                    break;
+                case 0x09:
+                    out += '\\t';
+                    break;
+                case 0x0a:
+                    out += '\\n';
+                    break;
+                case 0x0c:
+                    out += '\\f';
+                    break;
+                case 0x0d:
+                    out += '\\r';
+                    break;
+                default:
+                    out += `\\u${code.toString(16).padStart(4, '0')}`;
+            }
+        }
+        else {
+            out += s[i];
+        }
+    }
+    out += '"';
+    return out;
+}
+/** RFC 8785 §3.2.2.3 — shortest round-tripping IEEE 754 representation. */
+function serializeNumber(n, path) {
+    if (!Number.isFinite(n)) {
+        throw new JcsError(`non-finite number (${n})`, path);
+    }
+    if (Object.is(n, -0))
+        return '0';
+    if (n === 0)
+        return '0';
+    if (Number.isInteger(n) && Math.abs(n) < 1e21) {
+        return n.toString();
+    }
+    // Browsers + Node give us the shortest round-trip via `toString()`
+    // (per ECMA-262 §6.1.6.1.13). RFC 8785 expects the ES round-trip form.
+    return n.toString();
+}
+/**
+ * Compute the canonical hash of a value: `keccak256(jcsCanonicalize(value))`.
+ * Returns the 32-byte hex hash.
+ */
+export function canonicalHash(value) {
+    const canonical = jcsCanonicalize(value);
+    const bytes = utf8ToBytes(canonical);
+    const digest = keccak_256(bytes);
+    return `0x${bytesToHex(digest)}`;
+}
+function bytesToHex(b) {
+    let s = '';
+    for (const v of b) {
+        s += v.toString(16).padStart(2, '0');
+    }
+    return s;
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"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"}

package/dist/hash.d.ts

@@ -0,0 +1,4 @@
+import type { Hex32 } from '@agenticprimitives/types';
+import type { SituationV2 } from './types.js';
+export declare function hashSituationV2(s: SituationV2): Hex32;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,GAAG,KAAK,CAErD"}

package/dist/hash.js

@@ -0,0 +1,5 @@
+import { canonicalHash } from './canonical.js';
+export function hashSituationV2(s) {
+    return canonicalHash(s);
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,UAAU,eAAe,CAAC,CAAc;IAC5C,OAAO,aAAa,CAAC,CAAC,CAAU,CAAC;AACnC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export declare const PACKAGE_NAME = "@agenticprimitives/situations";
+export declare const PACKAGE_STATUS = "w2-situation-v2";
+export declare const SPEC_REF = "specs/324-unified-agent-organization-and-interaction-ontology.md";
+export type { DescriptionRef, EntityRef, RoleBindingV1, SituationEvidenceRef, SituationId, SituationValidity, SituationVaultRef, SituationV2, } from './types.js';
+export { SituationValidationError, assertDescriptionRef, assertEntityRef, assertRoleBindings, buildSituationV2, validateSituationV2, } from './validate.js';
+export { jcsCanonicalize, canonicalHash, JcsError } from './canonical.js';
+export { hashSituationV2 } from './hash.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,kCAAkC,CAAC;AAC5D,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAChD,eAAO,MAAM,QAAQ,qEAAqE,CAAC;AAE3F,YAAY,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// @agenticprimitives/situations — substrate Situation primitive (spec 324 W2).
+export const PACKAGE_NAME = '@agenticprimitives/situations';
+export const PACKAGE_STATUS = 'w2-situation-v2';
+export const SPEC_REF = 'specs/324-unified-agent-organization-and-interaction-ontology.md';
+export { SituationValidationError, assertDescriptionRef, assertEntityRef, assertRoleBindings, buildSituationV2, validateSituationV2, } from './validate.js';
+export { jcsCanonicalize, canonicalHash, JcsError } from './canonical.js';
+export { hashSituationV2 } from './hash.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,MAAM,CAAC,MAAM,YAAY,GAAG,+BAA+B,CAAC;AAC5D,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAChD,MAAM,CAAC,MAAM,QAAQ,GAAG,kEAAkE,CAAC;AAa3F,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+import type { CanonicalAgentId, Hex32 } from '@agenticprimitives/types';
+/** Ontology IRI of a Description / SHACL shape (e.g. `aporg:OrganizationMembership`). */
+export type DescriptionRef = `${string}:${string}`;
+export type SituationId = `sit_${string}`;
+/** Minimal vault record pointer — situations stays transport-agnostic (no vault import). */
+export interface SituationVaultRef {
+    recordKey: string;
+    owner?: string;
+    revision?: number;
+}
+export type EntityRef = {
+    kind: 'agent';
+    id: CanonicalAgentId;
+} | {
+    kind: 'situation';
+    id: SituationId;
+    hash?: Hex32;
+} | {
+    kind: 'resource';
+    iri: string;
+    hash?: Hex32;
+} | {
+    kind: 'artifact';
+    ref: SituationVaultRef;
+    hash: Hex32;
+};
+export interface RoleBindingV1 {
+    /** Ontology IRI, such as `aporg:memberAgent`. */
+    role: DescriptionRef;
+    fillers: EntityRef[];
+}
+export interface SituationEvidenceRef {
+    id: string;
+    hash?: Hex32;
+    type: string;
+}
+export interface SituationValidity {
+    validFrom: string;
+    validUntil?: string;
+}
+export interface SituationV2<TBody extends Record<string, unknown> = Record<string, unknown>> {
+    version: 'ap.situation.v2';
+    id: SituationId;
+    description: DescriptionRef;
+    roleBindings: RoleBindingV1[];
+    status?: string;
+    validity?: SituationValidity;
+    evidenceRefs?: SituationEvidenceRef[];
+    body: TBody;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAExE,yFAAyF;AACzF,MAAM,MAAM,cAAc,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG,OAAO,MAAM,EAAE,CAAC;AAE1C,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,gBAAgB,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,WAAW,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1F,OAAO,EAAE,iBAAiB,CAAC;IAC3B,EAAE,EAAE,WAAW,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;IAC5B,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,YAAY,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACtC,IAAI,EAAE,KAAK,CAAC;CACb"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validate.d.ts

@@ -0,0 +1,18 @@
+import type { DescriptionRef, EntityRef, RoleBindingV1, SituationV2 } from './types.js';
+export declare class SituationValidationError extends Error {
+    constructor(message: string);
+}
+export declare function assertDescriptionRef(ref: string): asserts ref is DescriptionRef;
+export declare function assertEntityRef(ref: EntityRef): void;
+export declare function assertRoleBindings(bindings: RoleBindingV1[]): void;
+export declare function validateSituationV2<TBody extends Record<string, unknown>>(s: SituationV2<TBody>): SituationV2<TBody>;
+export declare function buildSituationV2<TBody extends Record<string, unknown>>(args: {
+    id: SituationV2<TBody>['id'];
+    description: DescriptionRef;
+    roleBindings: RoleBindingV1[];
+    body: TBody;
+    status?: string;
+    validity?: SituationV2<TBody>['validity'];
+    evidenceRefs?: SituationV2<TBody>['evidenceRefs'];
+}): SituationV2<TBody>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAKxF,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,cAAc,CAI/E;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAmBpD;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI,CAQlE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvE,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,GACpB,WAAW,CAAC,KAAK,CAAC,CAQpB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE;IAC5E,EAAE,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7B,WAAW,EAAE,cAAc,CAAC;IAC5B,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;IAC1C,YAAY,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,CAAC;CACnD,GAAG,WAAW,CAAC,KAAK,CAAC,CAWrB"}

package/dist/validate.js

@@ -0,0 +1,69 @@
+const SIT_ID = /^sit_[a-zA-Z0-9_-]+$/;
+const DESC_REF = /^[a-z][a-z0-9-]*:[A-Za-z][A-Za-z0-9_-]*$/;
+export class SituationValidationError extends Error {
+    constructor(message) {
+        super(`[situations] ${message}`);
+        this.name = 'SituationValidationError';
+    }
+}
+export function assertDescriptionRef(ref) {
+    if (!DESC_REF.test(ref)) {
+        throw new SituationValidationError(`invalid DescriptionRef '${ref}'`);
+    }
+}
+export function assertEntityRef(ref) {
+    switch (ref.kind) {
+        case 'agent':
+            if (!ref.id?.includes(':'))
+                throw new SituationValidationError('agent filler requires CanonicalAgentId');
+            return;
+        case 'situation':
+            if (!SIT_ID.test(ref.id))
+                throw new SituationValidationError(`invalid situation id '${ref.id}'`);
+            return;
+        case 'resource':
+            if (!ref.iri)
+                throw new SituationValidationError('resource filler requires iri');
+            return;
+        case 'artifact':
+            if (!ref.ref?.recordKey || !ref.hash) {
+                throw new SituationValidationError('artifact filler requires ref.recordKey and hash');
+            }
+            return;
+        default:
+            throw new SituationValidationError('unknown EntityRef kind');
+    }
+}
+export function assertRoleBindings(bindings) {
+    for (const b of bindings) {
+        assertDescriptionRef(b.role);
+        if (!b.fillers?.length) {
+            throw new SituationValidationError(`role '${b.role}' requires at least one filler`);
+        }
+        for (const f of b.fillers)
+            assertEntityRef(f);
+    }
+}
+export function validateSituationV2(s) {
+    if (s.version !== 'ap.situation.v2') {
+        throw new SituationValidationError(`expected version ap.situation.v2, got ${String(s.version)}`);
+    }
+    if (!SIT_ID.test(s.id))
+        throw new SituationValidationError(`invalid situation id '${s.id}'`);
+    assertDescriptionRef(s.description);
+    assertRoleBindings(s.roleBindings ?? []);
+    return s;
+}
+export function buildSituationV2(args) {
+    return validateSituationV2({
+        version: 'ap.situation.v2',
+        id: args.id,
+        description: args.description,
+        roleBindings: args.roleBindings,
+        body: args.body,
+        status: args.status,
+        validity: args.validity,
+        evidenceRefs: args.evidenceRefs,
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@agenticprimitives/situations",
+  "version": "0.0.0-alpha.1",
+  "description": "Substrate Situation primitive (SituationV2, RoleBinding, EntityRef) — spec 324 W2.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentictrustlabs/agenticprimitives.git",
+    "directory": "packages/situations"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "spec.md",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.2.0",
+    "@agenticprimitives/types": "1.0.0-alpha.17"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
+  "keywords": [
+    "agentic",
+    "situation",
+    "ontology"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}

package/spec.md

@@ -0,0 +1 @@
+See [spec 324](../../specs/324-unified-agent-organization-and-interaction-ontology.md) §5 (Wave 2).