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

package/dist/src/shapes/resolver.js

@@ -0,0 +1,111 @@
+import { TopicProtocolError } from "../errors.js";
+import { topicRecipeForKind } from "../contracts/topic-contract.js";
+import { shapeDigest } from "./canonical.js";
+import { BASE_RECIPE_REGISTRY, KIND_SHAPE_REGISTRY, TOPIC_RECIPE_REGISTRY } from "./recipes.js";
+function replaceByCode(base, overlay) {
+    const values = new Map(base.map((value) => [value.code, value]));
+    for (const value of overlay)
+        values.set(value.code, value);
+    return [...values.values()].sort((left, right) => left.code.localeCompare(right.code));
+}
+function mergeShape(base, overlay) {
+    return {
+        version: 1,
+        code: overlay.code,
+        axes: replaceByCode(base.axes, overlay.axes ?? []),
+        transitions: replaceByCode(base.transitions, overlay.transitions ?? []),
+        progressRules: replaceByCode(base.progressRules, overlay.progressRules ?? []),
+        inferredRecordPolicy: {
+            autoAccept: [...new Set([...base.inferredRecordPolicy.autoAccept, ...overlay.inferredRecordPolicy.autoAccept])].sort(),
+            neverAutoAccept: [...new Set([...base.inferredRecordPolicy.neverAutoAccept, ...overlay.inferredRecordPolicy.neverAutoAccept])].sort(),
+        },
+    };
+}
+function validateAxis(axis) {
+    const states = new Set(axis.states.map(({ code }) => code));
+    if (states.has(axis.initialState) && states.size === axis.states.length)
+        return;
+    throw new TopicProtocolError("SHAPE_INVALID", `Shape axis is invalid: ${axis.code}`, { axis: axis.code });
+}
+function validateTransition(transition, axes) {
+    const predecessor = axes.get(transition.predecessor.axis);
+    const target = axes.get(transition.target.axis);
+    const valid = predecessor?.states.some(({ code }) => code === transition.predecessor.state) === true
+        && target?.states.some(({ code }) => code === transition.target.state) === true;
+    if (valid)
+        return;
+    throw new TopicProtocolError("SHAPE_INVALID", `Shape transition is invalid: ${transition.code}`, { transition: transition.code });
+}
+function validateShape(shape) {
+    for (const axis of shape.axes)
+        validateAxis(axis);
+    const axes = new Map(shape.axes.map((axis) => [axis.code, axis]));
+    for (const transition of shape.transitions)
+        validateTransition(transition, axes);
+    const completion = shape.transitions.filter(({ completesTopic }) => completesTopic === true);
+    if (completion.length === 1)
+        return;
+    throw new TopicProtocolError("SHAPE_INVALID", "A Shape must define exactly one Topic completion transition");
+}
+function recipeFor(ref, registry) {
+    const recipe = Object.values(registry).find(({ id, recipeVersion }) => id === ref.id && recipeVersion === ref.version);
+    if (recipe === undefined)
+        throw new TopicProtocolError("SHAPE_SOURCE_NOT_FOUND", `Topic Recipe not found: ${ref.id}`);
+    const digest = shapeDigest(recipe);
+    if (digest === ref.digest)
+        return recipe;
+    throw new TopicProtocolError("SHAPE_DIGEST_MISMATCH", `Topic Recipe digest does not match: ${ref.id}`, { expected: ref.digest, actual: digest });
+}
+function baseSource(baseRecipe, shape) {
+    return {
+        kind: "base-recipe",
+        id: `https://topic-protocol.ixo.world/base-recipes/${baseRecipe}`,
+        version: "1.0.0-rc.1",
+        digest: shapeDigest(shape),
+    };
+}
+export function resolveEffectiveTopicShape(input) {
+    const base = BASE_RECIPE_REGISTRY[input.baseRecipe];
+    let effective = base;
+    const sources = [baseSource(input.baseRecipe, base)];
+    if (input.topicRecipeRef !== undefined) {
+        const recipe = recipeFor(input.topicRecipeRef, input.recipeRegistry ?? TOPIC_RECIPE_REGISTRY);
+        if (recipe.baseRecipe !== input.baseRecipe) {
+            throw new TopicProtocolError("SHAPE_INVALID", "Topic Recipe does not extend the selected Base Recipe", {
+                baseRecipe: input.baseRecipe,
+                recipeBaseRecipe: recipe.baseRecipe,
+            });
+        }
+        effective = mergeShape(effective, recipe.shape);
+        sources.push({ kind: "topic-recipe", id: recipe.id, version: recipe.recipeVersion, digest: input.topicRecipeRef.digest });
+    }
+    if (input.kind !== undefined) {
+        const expectedBaseRecipe = topicRecipeForKind({ source: "standard", kind: input.kind });
+        if (expectedBaseRecipe !== input.baseRecipe) {
+            throw new TopicProtocolError("SHAPE_INVALID", "Topic Kind does not use the selected Base Recipe", {
+                kind: input.kind,
+                baseRecipe: input.baseRecipe,
+                expectedBaseRecipe,
+            });
+        }
+        const overlay = KIND_SHAPE_REGISTRY[input.kind];
+        effective = mergeShape(effective, overlay);
+        sources.push({
+            kind: "kind",
+            id: `https://topic-protocol.ixo.world/kinds/${input.kind}`,
+            version: "1.0.0-rc.1",
+            digest: shapeDigest(overlay),
+        });
+    }
+    for (const overlay of input.overlays ?? []) {
+        effective = mergeShape(effective, overlay.shape);
+        sources.push(overlay.source);
+    }
+    validateShape(effective);
+    const sortedSources = [...sources].sort((left, right) => `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`));
+    return { version: 1, shape: effective, sources: sortedSources, digest: shapeDigest({ shape: effective, sources: sortedSources }) };
+}
+export function topicRecipeRef(recipe) {
+    return { id: recipe.id, version: recipe.recipeVersion, digest: shapeDigest(recipe) };
+}
+//# sourceMappingURL=resolver.js.map

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

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

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

@@ -0,0 +1,53 @@
+import type { TopicContractBodyV3 } from "../contracts/topic-contract.js";
+import type { TopicFlowBindingV1 } from "../action-runtime/types.js";
+import type { TopicAnchor, TopicContractHeads, TopicRootV3 } from "../projector/types.js";
+import type { ResolvedTopicClaimBindingV1, TopicClaimBindingV1, TopicProgressProjectionV1, TopicShapeSourceRefV1 } from "./types.js";
+export declare const TOPIC_STATE_PROFILE_V3 = "qi.topic-contract-state/v3";
+export interface TopicContractReferenceV3 {
+    readonly revision: string;
+    readonly bodyHash: string;
+    readonly bodyRef: Readonly<Record<string, unknown>>;
+    readonly body?: TopicContractBodyV3;
+}
+export interface TopicStateBindingsV3 {
+    readonly flows?: readonly TopicFlowBindingV1[];
+    readonly context?: readonly {
+        readonly type: "ixo.resource" | "ixo.flow" | "matrix.conversation" | "ixo.entity" | "ixo.service";
+        readonly id: string;
+        readonly label?: string;
+    }[];
+    readonly udidReferences?: readonly {
+        readonly id: string;
+        readonly role: "evaluation" | "decision" | "effect" | "settlement";
+        readonly digest?: `sha256:${string}`;
+    }[];
+}
+export interface TopicContractStateV3 {
+    readonly version: 3;
+    readonly profile: typeof TOPIC_STATE_PROFILE_V3;
+    readonly schema: "https://topic-protocol.ixo.world/schemas/topic-contract-state.schema.json";
+    readonly topicId: string;
+    readonly anchor: TopicAnchor;
+    readonly manifest: TopicRootV3;
+    readonly contracts: TopicContractHeads;
+    readonly shape: {
+        readonly digest: `sha256:${string}`;
+        readonly sources: readonly TopicShapeSourceRefV1[];
+    };
+    readonly progress: TopicProgressProjectionV1;
+    readonly projection: {
+        readonly revision: string;
+        readonly contractRevision: string;
+        readonly title: string;
+        readonly status: TopicRootV3["status"];
+        readonly kindRef: TopicContractBodyV3["kindRef"];
+        readonly attachmentCount: number;
+        readonly operationCount: number;
+        readonly claimBinding?: TopicClaimBindingV1;
+        readonly claimResolution?: ResolvedTopicClaimBindingV1;
+    };
+    readonly policy: Readonly<Record<string, unknown>>;
+    readonly bindings: TopicStateBindingsV3;
+    readonly provenance: Readonly<Record<string, unknown>>;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+}

package/dist/src/shapes/state.js

@@ -0,0 +1,2 @@
+export const TOPIC_STATE_PROFILE_V3 = "qi.topic-contract-state/v3";
+//# sourceMappingURL=state.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/shapes/state.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC"}

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.8.0",
+  "version": "1.0.0-rc.1",
   "description": "Reference contracts and deterministic projection for IXO Topics",
   "type": "module",
   "sideEffects": false,
@@ -18,6 +18,7 @@
   "files": [
     "dist",
     "profiles",
+    "recipes",
     "templates",
     "README.md"
   ],
@@ -28,6 +29,7 @@
     },
     "./schemas/*": "./dist/schemas/*",
     "./profiles/*": "./profiles/*",
+    "./recipes/*": "./recipes/*",
     "./templates/*": "./templates/*"
   },
   "scripts": {

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.