@ixo/topic-protocol 0.7.0 → 1.0.0-rc.1

package/dist/src/shapes/types.d.ts

@@ -0,0 +1,241 @@
+export declare const SHAPE_PHASES: readonly ["forming", "working", "verifying", "deciding", "effecting", "settling", "complete", "dormant"];
+export declare const SHAPE_CONDITIONS: readonly ["on-track", "needs-input", "needs-acceptance", "waiting", "blocked", "failed", "disputed", "degraded"];
+export declare const SHAPE_ATTENTION_STATES: readonly ["none", "viewer-action-required", "viewer-review-required", "viewer-confirmation-required"];
+export declare const BASE_RECIPE_CODES: readonly ["project", "flow", "proposal", "evaluation", "claims", "research", "discussion", "incident"];
+export declare const TOPIC_RECIPE_CODES: readonly ["research-brief", "agent-delivery", "verified-work-payment"];
+export type ShapePhaseV1 = (typeof SHAPE_PHASES)[number];
+export type ShapeConditionV1 = (typeof SHAPE_CONDITIONS)[number];
+export type ShapeAttentionV1 = (typeof SHAPE_ATTENTION_STATES)[number];
+export type BaseRecipeCodeV1 = (typeof BASE_RECIPE_CODES)[number];
+export type TopicRecipeCodeV1 = (typeof TOPIC_RECIPE_CODES)[number];
+export type ShapeConsequenceClassV1 = "none" | "shared-state" | "external-effect" | "settlement";
+export type ShapeConfirmationPolicyV1 = "none" | "viewer" | "authority";
+export type ShapeEvidenceRequirementV1 = {
+    readonly kind: "operation" | "record" | "receipt";
+    readonly type: string;
+    readonly finality?: "observed" | "accepted" | "verified" | "final";
+};
+export type ShapeGateV1 = {
+    readonly kind: "field";
+    readonly path: string;
+    readonly predicate: "present" | "accepted";
+} | {
+    readonly kind: "field-any";
+    readonly paths: readonly string[];
+    readonly predicate: "present" | "accepted";
+} | {
+    readonly kind: "record";
+    readonly type: string;
+    readonly status?: string;
+} | {
+    readonly kind: "receipt";
+    readonly type: string;
+    readonly status?: string;
+} | {
+    readonly kind: "axis";
+    readonly axis: string;
+    readonly states: readonly string[];
+} | {
+    readonly kind: "binding";
+    readonly type: "flow" | "claim" | "resource";
+} | {
+    readonly kind: "condition";
+    readonly states: readonly ("waiting" | "blocked" | "failed" | "disputed")[];
+};
+export interface ShapeStateDefinitionV1 {
+    readonly code: string;
+    readonly labelKey?: string;
+    readonly terminal?: boolean;
+    readonly condition?: ShapeConditionV1;
+}
+export interface ShapeStateAxisV1 {
+    readonly code: string;
+    readonly phase: ShapePhaseV1;
+    readonly required: boolean;
+    readonly initialState: string;
+    readonly states: readonly ShapeStateDefinitionV1[];
+}
+export interface ShapeTransitionV1 {
+    readonly code: string;
+    readonly phase: ShapePhaseV1;
+    readonly predecessor: {
+        readonly axis: string;
+        readonly state: string;
+    };
+    readonly target: {
+        readonly axis: string;
+        readonly state: string;
+    };
+    readonly command: string;
+    readonly requiredAbility: string;
+    readonly assignedTo: {
+        readonly kind: "actor" | "role";
+        readonly value: string;
+    };
+    readonly gates: readonly ShapeGateV1[];
+    readonly confirmation: ShapeConfirmationPolicyV1;
+    readonly consequence: ShapeConsequenceClassV1;
+    readonly evidence: ShapeEvidenceRequirementV1;
+    readonly completesTopic?: boolean;
+    readonly handoff?: {
+        readonly kind: "flow" | "resource";
+        readonly binding: string;
+    };
+    readonly presentation?: {
+        readonly reasonCode: string;
+        readonly actionLabelKey?: string;
+    };
+}
+export interface ShapeProgressRuleV1 {
+    readonly code: string;
+    readonly condition: Exclude<ShapeConditionV1, "on-track" | "degraded">;
+    readonly priority: number;
+    readonly source: {
+        readonly kind: "axis" | "record" | "receipt" | "topic";
+        readonly value: string;
+    };
+    readonly states?: readonly string[];
+    readonly requiresTarget?: boolean;
+}
+export interface TopicShapeV1 {
+    readonly version: 1;
+    readonly code: string;
+    readonly axes: readonly ShapeStateAxisV1[];
+    readonly transitions: readonly ShapeTransitionV1[];
+    readonly progressRules: readonly ShapeProgressRuleV1[];
+    readonly inferredRecordPolicy: {
+        readonly autoAccept: readonly string[];
+        readonly neverAutoAccept: readonly string[];
+    };
+}
+export type TopicShapeOverlayV1 = Omit<TopicShapeV1, "axes" | "transitions" | "progressRules"> & {
+    readonly axes?: readonly ShapeStateAxisV1[];
+    readonly transitions?: readonly ShapeTransitionV1[];
+    readonly progressRules?: readonly ShapeProgressRuleV1[];
+};
+export interface TopicShapeSourceRefV1 {
+    readonly kind: "base-recipe" | "topic-recipe" | "kind" | "topic";
+    readonly id: string;
+    readonly version: string;
+    readonly digest: `sha256:${string}`;
+}
+export interface TopicRecipeRefV1 {
+    readonly id: string;
+    readonly version: string;
+    readonly digest: `sha256:${string}`;
+}
+export interface TopicRecipeV1 {
+    readonly version: 1;
+    readonly code: TopicRecipeCodeV1;
+    readonly id: string;
+    readonly recipeVersion: string;
+    readonly label: string;
+    readonly description: string;
+    readonly baseRecipe: BaseRecipeCodeV1;
+    readonly creates: "draft";
+    readonly shape: TopicShapeV1;
+}
+export interface EffectiveTopicShapeV1 {
+    readonly version: 1;
+    readonly shape: TopicShapeV1;
+    readonly sources: readonly TopicShapeSourceRefV1[];
+    readonly digest: `sha256:${string}`;
+}
+export interface TopicClaimBindingV1 {
+    readonly entityDid: string;
+    readonly collectionId: string;
+}
+export interface ResolvedTopicClaimBindingV1 extends TopicClaimBindingV1 {
+    readonly protocolDid: string;
+    readonly rubric: {
+        readonly id: string;
+        readonly digest?: `sha256:${string}`;
+    };
+}
+export interface TopicProgressSourceV1 {
+    readonly kind: "operation" | "record" | "receipt";
+    readonly type: string;
+    readonly id: string;
+    readonly status?: string;
+    readonly finality?: "observed" | "accepted" | "verified" | "final";
+}
+export interface TopicProgressBlockV1 {
+    readonly condition: "waiting" | "blocked" | "failed" | "disputed";
+    readonly sourceId: string;
+    readonly target: {
+        readonly kind: "actor" | "flow" | "resource" | "external";
+        readonly id: string;
+    };
+    readonly reasonCode: string;
+}
+export interface TopicProgressInputV1 {
+    readonly topicId: string;
+    readonly topicRevision: string;
+    readonly contractRevision: string;
+    readonly status: "draft" | "active" | "resolved" | "archived" | "redirected";
+    readonly shape?: EffectiveTopicShapeV1;
+    readonly historyCompatible: boolean;
+    readonly axisStates: Readonly<Record<string, string>>;
+    readonly sources: readonly TopicProgressSourceV1[];
+    readonly presentFields?: readonly string[];
+    readonly acceptedFields?: readonly string[];
+    readonly bindings?: readonly ("flow" | "claim" | "resource")[];
+    readonly actorAssignments?: Readonly<Record<string, readonly string[]>>;
+    readonly block?: TopicProgressBlockV1;
+}
+export interface TopicStateTagV1 {
+    readonly code: string;
+    readonly source: {
+        readonly axis: string;
+        readonly state: string;
+    } | {
+        readonly progressRule: string;
+    };
+    readonly priority: number;
+    readonly tone: "neutral" | "info" | "attention" | "warning" | "critical" | "positive";
+    readonly provenance: readonly string[];
+}
+export interface TopicTransitionCandidateV1 {
+    readonly transition: ShapeTransitionV1;
+    readonly assignedActor?: string;
+    readonly gateStatus: readonly {
+        readonly gate: ShapeGateV1;
+        readonly satisfied: boolean;
+    }[];
+}
+export interface TopicProgressProjectionV1 {
+    readonly version: 1;
+    readonly topicId: string;
+    readonly topicRevision: string;
+    readonly contractRevision: string;
+    readonly shapeDigest: `sha256:${string}`;
+    readonly phase: ShapePhaseV1;
+    readonly condition: ShapeConditionV1;
+    readonly reasonCode: string;
+    readonly axisStates: Readonly<Record<string, string>>;
+    readonly stateTags: readonly TopicStateTagV1[];
+    readonly candidates: readonly TopicTransitionCandidateV1[];
+    readonly provenance: readonly string[];
+    readonly block?: TopicProgressBlockV1;
+}
+export interface TopicViewerAuthorityV1 {
+    readonly viewerId: string;
+    readonly matrixWrite: boolean;
+    readonly verifiedAbilities: readonly string[];
+    readonly roleAssignments: Readonly<Record<string, readonly string[]>>;
+}
+export interface TopicNowProjectionV1 {
+    readonly version: 1;
+    readonly phase: ShapePhaseV1;
+    readonly condition: ShapeConditionV1;
+    readonly attention: ShapeAttentionV1;
+    readonly reasonCode: string;
+    readonly stateTags: readonly TopicStateTagV1[];
+    readonly transitions: readonly ShapeTransitionV1[];
+    readonly cacheKey: {
+        readonly topicRevision: string;
+        readonly contractRevision: string;
+        readonly shapeDigest: `sha256:${string}`;
+    };
+    readonly blockedOn?: TopicProgressBlockV1["target"];
+}

package/dist/src/shapes/types.js

@@ -0,0 +1,42 @@
+export const SHAPE_PHASES = [
+    "forming",
+    "working",
+    "verifying",
+    "deciding",
+    "effecting",
+    "settling",
+    "complete",
+    "dormant",
+];
+export const SHAPE_CONDITIONS = [
+    "on-track",
+    "needs-input",
+    "needs-acceptance",
+    "waiting",
+    "blocked",
+    "failed",
+    "disputed",
+    "degraded",
+];
+export const SHAPE_ATTENTION_STATES = [
+    "none",
+    "viewer-action-required",
+    "viewer-review-required",
+    "viewer-confirmation-required",
+];
+export const BASE_RECIPE_CODES = [
+    "project",
+    "flow",
+    "proposal",
+    "evaluation",
+    "claims",
+    "research",
+    "discussion",
+    "incident",
+];
+export const TOPIC_RECIPE_CODES = [
+    "research-brief",
+    "agent-delivery",
+    "verified-work-payment",
+];
+//# sourceMappingURL=types.js.map

package/dist/src/shapes/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/shapes/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,SAAS;IACT,SAAS;IACT,WAAW;IACX,UAAU;IACV,WAAW;IACX,UAAU;IACV,UAAU;IACV,SAAS;CACD,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,UAAU;IACV,aAAa;IACb,kBAAkB;IAClB,SAAS;IACT,SAAS;IACT,QAAQ;IACR,UAAU;IACV,UAAU;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,MAAM;IACN,wBAAwB;IACxB,wBAAwB;IACxB,8BAA8B;CACtB,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,SAAS;IACT,MAAM;IACN,UAAU;IACV,YAAY;IACZ,QAAQ;IACR,UAAU;IACV,YAAY;IACZ,UAAU;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,gBAAgB;IAChB,gBAAgB;IAChB,uBAAuB;CACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/topic-protocol",
-  "version": "0.7.0",
+  "version": "1.0.0-rc.1",
   "description": "Reference contracts and deterministic projection for IXO Topics",
   "type": "module",
   "sideEffects": false,
@@ -18,6 +18,8 @@
   "files": [
     "dist",
     "profiles",
+    "recipes",
+    "templates",
     "README.md"
   ],
   "exports": {
@@ -26,7 +28,9 @@
       "import": "./dist/src/index.js"
     },
     "./schemas/*": "./dist/schemas/*",
-    "./profiles/*": "./profiles/*"
+    "./profiles/*": "./profiles/*",
+    "./recipes/*": "./recipes/*",
+    "./templates/*": "./templates/*"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/recipes/README.md

@@ -0,0 +1,12 @@
+# Topic Recipe registry
+
+These digest-addressed Topic Recipes are Marketplace-ready release-candidate
+artifacts. Every recipe creates a user-reviewable Draft; none grants authority
+or executes its Flow bindings.
+
+- `research-brief.json`
+- `agent-delivery.json`
+- `verified-work-payment.json`
+
+`registry.json` publishes the corresponding immutable references. Consumers
+must verify the recipe digest before resolving the Effective Topic Shape.