@lssm/lib.communication-spec 3.1.1

package/dist/contracts/preference-resolution.d.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import type { CommunicationPreferenceSetV1 } from './channel-preferences.js';
+export declare const COMMUNICATION_PREFERENCE_RESOLUTION_SCHEMA_VERSION: '1.0.0';
+export declare const COMMUNICATION_PLATFORM_DEFAULT_PREFERENCE_TARGET_REF: 'communication:preference-target:platform-default';
+/** Resolution proceeds from the most specific available tier to the default. */
+export declare const COMMUNICATION_PREFERENCE_RESOLUTION_TIERS: readonly [readonly ['event', 'automation'], readonly ['feature', 'application'], readonly ['product'], readonly ['space', 'person'], readonly ['platform_default']];
+export declare const CommunicationPreferenceResolutionTargetKindSchema: z.ZodEnum<{
+    application: "application";
+    automation: "automation";
+    event: "event";
+    feature: "feature";
+    person: "person";
+    platform_default: "platform_default";
+    product: "product";
+    space: "space";
+}>;
+/** Exactly one typed resolution target and its opaque canonical reference. */
+export declare const CommunicationPreferenceResolutionTargetV1Schema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"event">;
+    ref: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"automation">;
+    ref: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"feature">;
+    ref: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"application">;
+    ref: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"product">;
+    ref: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"space">;
+    ref: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"person">;
+    ref: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"platform_default">;
+    ref: z.ZodLiteral<"communication:preference-target:platform-default">;
+}, z.core.$strict>], "kind">;
+export declare const CommunicationEvaluatedPreferenceSetV1Schema: z.ZodObject<{
+    preferenceSetRef: z.ZodString;
+    revision: z.ZodNumber;
+    digest: z.ZodString;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"event">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"automation">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"feature">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"application">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"product">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"space">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"person">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"platform_default">;
+        ref: z.ZodLiteral<"communication:preference-target:platform-default">;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+/** Replayable preference evaluation evidence; it grants no send authority. */
+export declare const CommunicationPreferenceResolutionResultV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1.0.0">;
+    resolutionRef: z.ZodString;
+    scope: z.ZodObject<{
+        tenantRef: z.ZodString;
+        workspaceRef: z.ZodOptional<z.ZodString>;
+        spaceRef: z.ZodOptional<z.ZodString>;
+        subjectRef: z.ZodString;
+    }, z.core.$strict>;
+    subjectRef: z.ZodString;
+    evaluatedPreferenceSets: z.ZodArray<z.ZodObject<{
+        preferenceSetRef: z.ZodString;
+        revision: z.ZodNumber;
+        digest: z.ZodString;
+        target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"event">;
+            ref: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"automation">;
+            ref: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"feature">;
+            ref: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"application">;
+            ref: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"product">;
+            ref: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"space">;
+            ref: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"person">;
+            ref: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"platform_default">;
+            ref: z.ZodLiteral<"communication:preference-target:platform-default">;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>>;
+    winningPreferenceSetRef: z.ZodString;
+    winningTarget: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"event">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"automation">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"feature">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"application">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"product">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"space">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"person">;
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"platform_default">;
+        ref: z.ZodLiteral<"communication:preference-target:platform-default">;
+    }, z.core.$strict>], "kind">;
+    authority: z.ZodLiteral<"preference_only">;
+    effectAuthority: z.ZodLiteral<"none">;
+    resolvedAt: z.ZodString;
+    evidenceRefs: z.ZodArray<z.ZodString>;
+    resolutionDigest: z.ZodString;
+}, z.core.$strict>;
+export type CommunicationPreferenceResolutionTargetKind = z.infer<typeof CommunicationPreferenceResolutionTargetKindSchema>;
+export type CommunicationPreferenceResolutionTargetV1 = z.infer<typeof CommunicationPreferenceResolutionTargetV1Schema>;
+export type CommunicationEvaluatedPreferenceSetV1 = z.infer<typeof CommunicationEvaluatedPreferenceSetV1Schema>;
+export type CommunicationPreferenceResolutionResultV1 = z.infer<typeof CommunicationPreferenceResolutionResultV1Schema>;
+/** Pure validation of the winning result against its persisted preference set. */
+export declare function validateCommunicationPreferenceResolutionBindingV1(input: {
+    preferenceResolution: CommunicationPreferenceResolutionResultV1;
+    preferenceSet: CommunicationPreferenceSetV1;
+}): string[];

package/dist/contracts/preference-resolution.js

@@ -0,0 +1,2 @@
+// @bun
+import{z as c}from"zod";import{z as r}from"zod";var C="1.0.0",P="1.0.0",I={id:"communication-os.agent-omnichannel.v1",title:"CommunicationOS agent omnichannel contracts",body:"Provider-neutral agent profiles and lifecycle links bind applications, runs, tasks, help requests, background results, routes, preferences, policies, and evidence through opaque references. They grant no provider access or effect authority.",kind:"reference",route:"/docs/communication-os/agent-omnichannel-v1",visibility:"public"},o=r.string().trim().min(1),h=r.string().datetime({offset:!0}),m=r.string().regex(/^sha256:[a-f0-9]{64}$/),S=r.object({ref:o,digest:m}).strict(),l=S.extend({revision:r.number().int().positive()}).strict(),d=r.object({tenantRef:o,workspaceRef:o.optional(),spaceRef:o.optional(),subjectRef:o}).strict(),k=r.object({schemaVersion:r.literal(C),profileRef:o,revision:r.number().int().positive(),agentRef:o,applicationRef:o,scope:d,routeBindings:r.array(l),connectionRefs:r.array(o),preferenceSet:l,policyRefs:r.array(o).min(1),evidenceRefs:r.array(o).min(1),createdAt:h,updatedAt:h,profileDigest:m}).strict().superRefine((e,t)=>{for(let i of["connectionRefs","policyRefs","evidenceRefs"])if(new Set(e[i]).size!==e[i].length)t.addIssue({code:r.ZodIssueCode.custom,path:[i],message:`${i} must be unique`});let n=e.routeBindings.map((i)=>i.ref);if(new Set(n).size!==n.length)t.addIssue({code:r.ZodIssueCode.custom,path:["routeBindings"],message:"route bindings must be unique"})}),T=r.object({schemaVersion:r.literal(P),linkRef:o,profile:l,agentRef:o,applicationRef:o,scope:d,runRef:o.optional(),taskRef:o.optional(),helpRequestRef:o.optional(),approvalRequestRef:o.optional(),backgroundResultRef:o.optional(),canonicalConversation:S.optional(),session:l.optional(),correlationRef:o,evidenceRefs:r.array(o).min(1)}).strict().superRefine((e,t)=>{if(new Set(e.evidenceRefs).size!==e.evidenceRefs.length)t.addIssue({code:r.ZodIssueCode.custom,path:["evidenceRefs"],message:"evidenceRefs must be unique"});if(!e.runRef&&!e.taskRef&&!e.helpRequestRef&&!e.approvalRequestRef&&!e.backgroundResultRef)t.addIssue({code:r.ZodIssueCode.custom,path:["runRef"],message:"at least one run, task, help request, approval request, or background result ref is required"})});function g(e,t){return e.tenantRef===t.tenantRef&&e.workspaceRef===t.workspaceRef&&e.spaceRef===t.spaceRef&&e.subjectRef===t.subjectRef}function w(e){let t=[];for(let n of["agentRef","applicationRef"])if(e.profile[n]!==e.lifecycleLink[n])t.push(`Lifecycle ${n} does not match the agent profile`);if(e.lifecycleLink.profile.ref!==e.profile.profileRef||e.lifecycleLink.profile.revision!==e.profile.revision||e.lifecycleLink.profile.digest!==e.profile.profileDigest)t.push("Lifecycle profile binding does not match the agent profile");if(!g(e.profile.scope,e.lifecycleLink.scope))t.push("Lifecycle scope does not match the agent profile");return t}function x(e){let{intent:t,progress:n}=e,i=[];if(n.deliveryRef!==t.deliveryRef||n.intent.ref!==t.deliveryRef||n.intent.digest!==t.deliveryDigest)i.push("Progress delivery does not match the intent");if(!g(n.scope,t.scope))i.push("Progress scope does not match the intent");if(n.recipientRef!==t.recipientRefs[0])i.push("Progress recipient does not match the intent");let s=t.requestedRoutes.find((f)=>f.ref===n.route.ref);if(!s||s.revision!==n.route.revision||s.digest!==n.route.digest)i.push("Progress route was not requested by the intent");if(Date.parse(n.occurredAt)<Date.parse(t.createdAt)||Date.parse(n.occurredAt)>Date.parse(t.expiresAt))i.push("Progress occurred outside the intent validity window");return i}var V="1.0.0",b="communication:preference-target:platform-default",N=[["event","automation"],["feature","application"],["product"],["space","person"],["platform_default"]],O=c.enum(["event","automation","feature","application","product","space","person","platform_default"]),p=c.string().trim().min(1);function a(e){return c.object({kind:c.literal(e),ref:p}).strict()}var y=c.discriminatedUnion("kind",[a("event"),a("automation"),a("feature"),a("application"),a("product"),a("space"),a("person"),c.object({kind:c.literal("platform_default"),ref:c.literal(b)}).strict()]),A=c.object({preferenceSetRef:p,revision:c.number().int().positive(),digest:m,target:y}).strict(),D=c.object({schemaVersion:c.literal(V),resolutionRef:p,scope:d,subjectRef:p,evaluatedPreferenceSets:c.array(A).min(1),winningPreferenceSetRef:p,winningTarget:y,authority:c.literal("preference_only"),effectAuthority:c.literal("none"),resolvedAt:c.string().datetime({offset:!0}),evidenceRefs:c.array(p).min(1),resolutionDigest:m}).strict().superRefine((e,t)=>{let n=e.evaluatedPreferenceSets.map((s)=>s.preferenceSetRef);if(new Set(n).size!==n.length)u(t,"evaluatedPreferenceSets","evaluated sets must be unique");if(new Set(e.evidenceRefs).size!==e.evidenceRefs.length)u(t,"evidenceRefs","evidenceRefs must be unique");for(let s=1;s<e.evaluatedPreferenceSets.length;s+=1){let f=e.evaluatedPreferenceSets[s-1],R=e.evaluatedPreferenceSets[s];if(f&&R&&v(f.target.kind)>v(R.target.kind)){u(t,"evaluatedPreferenceSets","evaluated sets must follow the preference resolution hierarchy");break}}let i=e.evaluatedPreferenceSets.find((s)=>s.preferenceSetRef===e.winningPreferenceSetRef);if(!i)u(t,"winningPreferenceSetRef","winning preference set must have been evaluated");else if(i.preferenceSetRef!==e.evaluatedPreferenceSets[0]?.preferenceSetRef)u(t,"winningPreferenceSetRef","winning preference set must be the most specific evaluated set");else if(i.target.kind!==e.winningTarget.kind||i.target.ref!==e.winningTarget.ref)u(t,"winningTarget","winning target must match the winning preference set")});function v(e){switch(e){case"event":case"automation":return 0;case"feature":case"application":return 1;case"product":return 2;case"space":case"person":return 3;case"platform_default":return 4}}function u(e,t,n){e.addIssue({code:c.ZodIssueCode.custom,path:[t],message:n})}function q(e){let{preferenceResolution:t,preferenceSet:n}=e,i=[];if(t.subjectRef!==n.scope.subjectRef||t.winningPreferenceSetRef!==n.preferenceSetRef)i.push("Preference resolution does not match its subject and set");if(!g(t.scope,n.scope))i.push("Preference resolution scope does not match its preference set");let s=t.evaluatedPreferenceSets.find((f)=>f.preferenceSetRef===n.preferenceSetRef);if(!s||s.revision!==n.revision||s.digest!==n.preferenceSetDigest)i.push("Preference resolution binding is stale");if(t.winningTarget.kind!==n.target.kind||t.winningTarget.ref!==n.target.ref)i.push("Preference resolution target does not match its preference set");return i}export{b as COMMUNICATION_PLATFORM_DEFAULT_PREFERENCE_TARGET_REF,V as COMMUNICATION_PREFERENCE_RESOLUTION_SCHEMA_VERSION,N as COMMUNICATION_PREFERENCE_RESOLUTION_TIERS,A as CommunicationEvaluatedPreferenceSetV1Schema,D as CommunicationPreferenceResolutionResultV1Schema,O as CommunicationPreferenceResolutionTargetKindSchema,y as CommunicationPreferenceResolutionTargetV1Schema,q as validateCommunicationPreferenceResolutionBindingV1};

package/dist/contracts/preference-resolution.test.d.ts

@@ -0,0 +1 @@
+export {};