@tomflow/proflow-platform-host 0.1.29 → 0.1.31

package/dist/src/operation-observability.js

@@ -172,6 +172,9 @@ export function createHostOperationObserver(emit) {
             const errorCode = errorValue && typeof errorValue === "object"
                 ? code(Reflect.get(errorValue, "code")) ?? code(Reflect.get(errorValue, "message"))
                 : undefined;
+            const sideEffectState = Reflect.get(result, "sideEffectState");
+            const hasAuthoritativeSideEffectState = typeof sideEffectState === "string" &&
+                ["NOT_STARTED", "STARTED", "APPLIED", "NOT_APPLIED", "UNKNOWN"].includes(sideEffectState);
             const entry = {
                 contract: "proflow.operation-boundary.v1",
                 eventId: `host-event:${randomUUID()}`,
@@ -194,7 +197,7 @@ export function createHostOperationObserver(emit) {
                 ...axes,
                 decision: code(Reflect.get(result, "decision")), reason: code(Reflect.get(result, "reason")),
                 status: failed ? "FAILED" : Reflect.get(result, "decision") === "HUMAN_REQUIRED" ? "BLOCKED" : Reflect.get(result, "decision") === "DEFER" ? "DEFERRED" : "SUCCEEDED",
-                sideEffectState: ["APPLIED", "NOT_APPLIED", "NOT_STARTED", "UNKNOWN"].includes(String(Reflect.get(result, "sideEffectState"))) ? String(Reflect.get(result, "sideEffectState")) : "UNKNOWN",
+                ...(hasAuthoritativeSideEffectState ? { sideEffectState } : {}),
                 ...(failed
                     ? { errorCode: errorCode ?? "HOST_APPLICATION_FAILED" }
                     : {}),

package/dist/src/product-campaign-continuation.d.ts

@@ -0,0 +1,132 @@
+export declare const productDiscussionQueryOperationIds: Set<string>;
+export declare const productDiscussionMutationOperationIds: Set<string>;
+export type ProductRoleBinding = {
+    agentPackageRef: string;
+    roleRef: string;
+};
+export type ProductDiscussionSessionFact = {
+    discussionRef: string;
+    roleRef: string;
+    conversationRef: string;
+    conversationLocator: string;
+    campaignRef: string | null;
+    goalRevision: number | null;
+    currentIntentRef: string | null;
+    generation: number;
+    status: "ACTIVE" | "CLOSED";
+    version: number;
+};
+export type ProductDiscussionAdmissionVerificationInput = {
+    discussionRef: string;
+    roleRef: string;
+    conversationRef: string;
+    conversationLocator: string;
+    generation: number;
+    discussionAdmissionToken: string;
+};
+export type ProductContinuationProjection = {
+    campaign: {
+        campaignRef: string;
+        discussionRef: string;
+        goalRevision: number;
+        version: number;
+        status: "OPEN" | "CLOSED";
+    };
+    intent: {
+        intentRef: string;
+        version: number;
+    } | null;
+    task: {
+        taskId: string;
+        status: string;
+        version: number;
+    } | null;
+    authorization: {
+        authorizationRef: string;
+        version: number;
+    } | null;
+    requirementRevision: number | null;
+    nextAction: "NONE" | "PROVISION" | "TRANSFER_REQUIREMENT" | "CONSIDER_START" | "PRODUCT_REVIEW_REQUIRED";
+};
+export type ProductReviewSignal = {
+    kind: "PRODUCT_REVIEW_REQUIRED";
+    reviewRef: string;
+    campaignRef: string;
+    taskId: string;
+    terminalTaskVersion: number;
+    intentRef: string;
+    discussionRef: string;
+    discussionGeneration: number;
+    roleRef: string;
+    conversationRef: string;
+    conversationLocator: string;
+};
+export type ProductContinuationOutcome = {
+    kind: "NOT_CAMPAIGN";
+    taskId: string;
+} | {
+    kind: "IDLE";
+    taskId: string;
+} | {
+    kind: "AUTHORIZATION_REQUIRED";
+    taskId: string;
+} | {
+    kind: "TASK_STARTED";
+    taskId: string;
+} | ProductReviewSignal;
+export declare class ProductCampaignContinuationError extends Error {
+    readonly code: string;
+    readonly httpStatus: number;
+    constructor(code: string, httpStatus?: number);
+}
+export declare function canonicalizeProductOperation(input: {
+    operationId: string;
+    authenticatedRoleRef: string;
+    rawInput: unknown;
+    getDiscussionSession: (discussionRef: string) => ProductDiscussionSessionFact;
+    getRoleBindings: () => readonly ProductRoleBinding[];
+    verifyDiscussionAdmission?: (input: ProductDiscussionAdmissionVerificationInput) => boolean;
+}): {
+    scope: "TASK" | "PRODUCT_QUERY" | "PRODUCT_MUTATION";
+    input: Record<string, unknown>;
+    actorRef?: string;
+    kickContinuation: boolean;
+};
+export declare function createProductCampaignContinuationCoordinator(options: {
+    getProjection: (taskId: string) => Promise<ProductContinuationProjection | null>;
+    listTaskIds: () => Promise<readonly string[]>;
+    ensureWorkers: (taskId: string) => Promise<void>;
+    transferRequirement: (input: {
+        intentRef: string;
+        taskId: string;
+        expectedIntentVersion: number;
+        expectedTaskVersion: number;
+        idempotencyKey: string;
+    }) => Promise<void>;
+    startTask: (input: {
+        taskId: string;
+        expectedTaskVersion: number;
+        authorizationRef: string;
+        expectedAuthorizationVersion: number;
+        expectedCampaignVersion: number;
+        idempotencyKey: string;
+    }) => Promise<void>;
+    getDiscussionSessionForCampaign: (campaignRef: string) => ProductDiscussionSessionFact | undefined;
+    updateDiscussionSessionContext: (input: {
+        discussionRef: string;
+        expectedVersion: number;
+        campaignRef: string;
+        goalRevision: number;
+        currentIntentRef: string;
+    }) => ProductDiscussionSessionFact;
+    kickTaskReconciliation: (taskId: string) => void;
+    onProductReviewRequired?: (signal: ProductReviewSignal) => void | Promise<void>;
+    retryDelayMs?: number;
+}): Readonly<{
+    start(): void;
+    kick: (taskId: string) => void;
+    reconcile: (taskId: string) => Promise<ProductContinuationOutcome>;
+    sweep: () => Promise<ProductContinuationOutcome[]>;
+    drain(): Promise<void>;
+    stop(): void;
+}>;

package/dist/src/product-campaign-continuation.js

@@ -0,0 +1,279 @@
+export const productDiscussionQueryOperationIds = new Set([
+    "getProductCampaign",
+    "getProductDiscussionContext",
+    "getProductDocument",
+    "getCampaignAuthorization",
+]);
+export const productDiscussionMutationOperationIds = new Set([
+    "submitProductTaskIntent",
+    "putProductDocument",
+    "recordProductGapReview",
+    "recordProductGoalSatisfied",
+]);
+export class ProductCampaignContinuationError extends Error {
+    code;
+    httpStatus;
+    constructor(code, httpStatus = 409) {
+        super(code);
+        this.code = code;
+        this.httpStatus = httpStatus;
+    }
+}
+function record(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new ProductCampaignContinuationError(`${label.toUpperCase()}_INVALID`, 400);
+    return value;
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new ProductCampaignContinuationError(`${label.toUpperCase()}_REQUIRED`, 400);
+    return value;
+}
+function requiredGeneration(value) {
+    if (!Number.isInteger(value) || Number(value) <= 0)
+        throw new ProductCampaignContinuationError("PRODUCT_DISCUSSION_GENERATION_REQUIRED", 400);
+    return Number(value);
+}
+export function canonicalizeProductOperation(input) {
+    const raw = record(input.rawInput, "product action input");
+    const productQuery = productDiscussionQueryOperationIds.has(input.operationId);
+    const productMutation = productDiscussionMutationOperationIds.has(input.operationId);
+    if (!productQuery && !productMutation)
+        return { scope: "TASK", input: raw, kickContinuation: false };
+    const canonical = { ...raw };
+    delete canonical.roleRef;
+    delete canonical.actorRef;
+    delete canonical.workerRef;
+    delete canonical.roleBindings;
+    const discussionRef = requiredString(canonical.discussionRef, "discussionRef");
+    const discussionGeneration = requiredGeneration(canonical.discussionGeneration);
+    const session = input.getDiscussionSession(discussionRef);
+    if (session.status !== "ACTIVE" ||
+        session.roleRef !== input.authenticatedRoleRef)
+        throw new ProductCampaignContinuationError("PRODUCT_DISCUSSION_MISMATCH", 403);
+    if (session.generation !== discussionGeneration)
+        throw new ProductCampaignContinuationError("PRODUCT_DISCUSSION_GENERATION_MISMATCH", 403);
+    if (!input.verifyDiscussionAdmission)
+        throw new ProductCampaignContinuationError("PRODUCT_DISCUSSION_ADMISSION_UNAVAILABLE", 503);
+    const discussionAdmissionToken = requiredString(canonical.discussionAdmissionToken, "discussionAdmissionToken");
+    if (!input.verifyDiscussionAdmission({
+        discussionRef,
+        roleRef: session.roleRef,
+        conversationRef: session.conversationRef,
+        conversationLocator: session.conversationLocator,
+        generation: discussionGeneration,
+        discussionAdmissionToken,
+    }))
+        throw new ProductCampaignContinuationError("PRODUCT_DISCUSSION_ADMISSION_INVALID", 403);
+    delete canonical.discussionAdmissionToken;
+    if (typeof canonical.campaignRef === "string" &&
+        session.campaignRef !== canonical.campaignRef)
+        throw new ProductCampaignContinuationError("PRODUCT_DISCUSSION_CAMPAIGN_MISMATCH", 403);
+    if (typeof canonical.goalRevision === "number" &&
+        session.goalRevision !== null &&
+        session.goalRevision !== canonical.goalRevision)
+        throw new ProductCampaignContinuationError("PRODUCT_DISCUSSION_GOAL_REVISION_MISMATCH", 403);
+    delete canonical.discussionGeneration;
+    if (productQuery) {
+        if (input.operationId !== "getProductDocument")
+            delete canonical.discussionRef;
+        if (input.operationId === "getProductDocument")
+            requiredString(canonical.campaignRef, "campaignRef");
+        if (input.operationId === "getCampaignAuthorization") {
+            requiredString(canonical.campaignRef, "campaignRef");
+            delete canonical.campaignRef;
+        }
+        return {
+            scope: "PRODUCT_QUERY",
+            input: canonical,
+            kickContinuation: false,
+        };
+    }
+    if (input.operationId === "submitProductTaskIntent")
+        canonical.roleBindings = input
+            .getRoleBindings()
+            .map((binding) => ({ ...binding }));
+    return {
+        scope: "PRODUCT_MUTATION",
+        input: canonical,
+        actorRef: `product-discussion:${discussionRef}`,
+        kickContinuation: input.operationId === "submitProductTaskIntent",
+    };
+}
+export function createProductCampaignContinuationCoordinator(options) {
+    const retryDelayMs = Math.max(50, options.retryDelayMs ?? 500);
+    const inFlight = new Map();
+    const retryTimers = new Map();
+    let stopped = false;
+    let scanTimer;
+    let started = false;
+    let scanInFlight;
+    const reconcileOnce = async (taskId) => {
+        for (let step = 0; step < 6; step += 1) {
+            if (stopped)
+                return { kind: "IDLE", taskId };
+            const projection = await options.getProjection(taskId);
+            if (stopped)
+                return { kind: "IDLE", taskId };
+            if (!projection)
+                return { kind: "NOT_CAMPAIGN", taskId };
+            if (projection.nextAction === "NONE")
+                return { kind: "IDLE", taskId };
+            if (!projection.task || !projection.intent)
+                throw new ProductCampaignContinuationError("PRODUCT_CONTINUATION_FACTS_INCOMPLETE");
+            if (projection.nextAction === "PROVISION") {
+                await options.ensureWorkers(taskId);
+                continue;
+            }
+            if (projection.nextAction === "TRANSFER_REQUIREMENT") {
+                if (projection.requirementRevision === null)
+                    throw new ProductCampaignContinuationError("PRODUCT_REQUIREMENT_REVISION_MISSING");
+                await options.transferRequirement({
+                    intentRef: projection.intent.intentRef,
+                    taskId,
+                    expectedIntentVersion: projection.intent.version,
+                    expectedTaskVersion: projection.task.version,
+                    idempotencyKey: `transfer:${projection.intent.intentRef}:${taskId}:${projection.requirementRevision}`,
+                });
+                continue;
+            }
+            if (projection.nextAction === "CONSIDER_START") {
+                if (!projection.authorization)
+                    return { kind: "AUTHORIZATION_REQUIRED", taskId };
+                await options.startTask({
+                    taskId,
+                    expectedTaskVersion: projection.task.version,
+                    authorizationRef: projection.authorization.authorizationRef,
+                    expectedAuthorizationVersion: projection.authorization.version,
+                    expectedCampaignVersion: projection.campaign.version,
+                    idempotencyKey: `auto-start:${projection.authorization.authorizationRef}:${taskId}:${projection.task.version}`,
+                });
+                options.kickTaskReconciliation(taskId);
+                return { kind: "TASK_STARTED", taskId };
+            }
+            const session = options.getDiscussionSessionForCampaign(projection.campaign.campaignRef);
+            if (!session ||
+                session.status !== "ACTIVE" ||
+                session.discussionRef !== projection.campaign.discussionRef ||
+                session.campaignRef !== projection.campaign.campaignRef ||
+                (session.goalRevision !== null &&
+                    session.goalRevision !== projection.campaign.goalRevision))
+                throw new ProductCampaignContinuationError("PRODUCT_DISCUSSION_SESSION_NOT_READY");
+            const currentSession = session.currentIntentRef === projection.intent.intentRef
+                ? session
+                : options.updateDiscussionSessionContext({
+                    discussionRef: session.discussionRef,
+                    expectedVersion: session.version,
+                    campaignRef: projection.campaign.campaignRef,
+                    goalRevision: projection.campaign.goalRevision,
+                    currentIntentRef: projection.intent.intentRef,
+                });
+            const signal = {
+                kind: "PRODUCT_REVIEW_REQUIRED",
+                reviewRef: `product-review:${projection.campaign.campaignRef}:${taskId}:${projection.task.version}:${currentSession.discussionRef}:${currentSession.generation}`,
+                campaignRef: projection.campaign.campaignRef,
+                taskId,
+                terminalTaskVersion: projection.task.version,
+                intentRef: projection.intent.intentRef,
+                discussionRef: currentSession.discussionRef,
+                discussionGeneration: currentSession.generation,
+                roleRef: currentSession.roleRef,
+                conversationRef: currentSession.conversationRef,
+                conversationLocator: currentSession.conversationLocator,
+            };
+            await options.onProductReviewRequired?.(signal);
+            return signal;
+        }
+        throw new ProductCampaignContinuationError("PRODUCT_CONTINUATION_STEP_LIMIT");
+    };
+    const reconcile = (taskId) => {
+        const current = inFlight.get(taskId);
+        if (current)
+            return current;
+        const run = reconcileOnce(taskId).finally(() => inFlight.delete(taskId));
+        inFlight.set(taskId, run);
+        return run;
+    };
+    const scheduleRetry = (taskId) => {
+        if (stopped || retryTimers.has(taskId))
+            return;
+        const timer = setTimeout(() => {
+            retryTimers.delete(taskId);
+            if (!stopped)
+                void reconcile(taskId).catch(() => scheduleRetry(taskId));
+        }, retryDelayMs);
+        timer.unref?.();
+        retryTimers.set(taskId, timer);
+    };
+    const kick = (taskId) => {
+        if (stopped)
+            return;
+        void reconcile(taskId).catch(() => scheduleRetry(taskId));
+    };
+    const sweep = async () => {
+        if (stopped)
+            return [];
+        const taskIds = await options.listTaskIds();
+        const outcomes = [];
+        const failures = [];
+        for (let index = 0; !stopped && index < taskIds.length; index += 4) {
+            const batch = await Promise.allSettled(taskIds.slice(index, index + 4).map((taskId) => reconcile(taskId).catch((error) => {
+                scheduleRetry(taskId);
+                throw error;
+            })));
+            for (const result of batch) {
+                if (result.status === "fulfilled")
+                    outcomes.push(result.value);
+                else
+                    failures.push(result.reason);
+            }
+        }
+        if (failures.length > 0)
+            throw failures[0];
+        return outcomes;
+    };
+    const scan = async () => {
+        let delay = 30_000;
+        try {
+            await sweep();
+        }
+        catch {
+            delay = retryDelayMs;
+        }
+        finally {
+            if (!stopped) {
+                scanTimer = setTimeout(() => {
+                    scanInFlight = scan();
+                }, delay);
+                scanTimer.unref?.();
+            }
+        }
+    };
+    return Object.freeze({
+        start() {
+            if (stopped)
+                throw new ProductCampaignContinuationError("PRODUCT_CONTINUATION_STOPPED");
+            if (started)
+                return;
+            started = true;
+            scanInFlight = scan();
+        },
+        kick,
+        reconcile,
+        sweep,
+        async drain() {
+            await Promise.allSettled([
+                ...(scanInFlight ? [scanInFlight] : []),
+                ...inFlight.values(),
+            ]);
+        },
+        stop() {
+            stopped = true;
+            if (scanTimer)
+                clearTimeout(scanTimer);
+            for (const timer of retryTimers.values())
+                clearTimeout(timer);
+            retryTimers.clear();
+        },
+    });
+}

package/dist/src/product-discussion-admission.d.ts

@@ -0,0 +1,92 @@
+export type ProductDiscussionConversationIdentity = Readonly<{
+    roleRef: string;
+    conversationRef: string;
+    conversationLocator: string;
+}>;
+export type ProductDiscussionAdmission = Readonly<{
+    discussionRef: string;
+    roleRef: string;
+    conversationRef: string;
+    conversationLocator: string;
+    generation: number;
+    contentInstanceId: string;
+    bootstrapRef: string;
+    discussionAdmissionToken: string;
+}>;
+export type ProductDiscussionAdmissionVerification = Readonly<{
+    discussionRef: string;
+    roleRef: string;
+    conversationRef: string;
+    conversationLocator: string;
+    generation: number;
+    discussionAdmissionToken: string;
+}>;
+export type ProductDiscussionSessionOwnerFact = Readonly<{
+    discussionRef: string;
+    roleRef: string;
+    conversationRef: string;
+    conversationLocator: string;
+    generation: number;
+    status: "ACTIVE" | "CLOSED";
+}>;
+export type ProductDiscussionTaskRoleBindingFact = Readonly<{
+    roleRef: string;
+    workerRef: string | null;
+    conversationLocator: string | null;
+}>;
+type RandomBytes = (size: number) => Uint8Array;
+export declare function parseProductDiscussionConversationLocator(value: string): ProductDiscussionConversationIdentity | null;
+export declare function productDiscussionRef(identity: ProductDiscussionConversationIdentity): string;
+export declare function createProductDiscussionAdmissionAuthority(options?: {
+    randomBytesImpl?: RandomBytes;
+    now?: () => number;
+}): Readonly<{
+    ensure: (input: {
+        discussionRef: string;
+        roleRef: string;
+        conversationRef: string;
+        conversationLocator: string;
+        generation: number;
+        contentInstanceId: string;
+    }) => ProductDiscussionAdmission;
+    verify: (input: ProductDiscussionAdmissionVerification) => boolean;
+    get(discussionRef: string): ProductDiscussionAdmission | undefined;
+    revoke(discussionRef: string): boolean;
+    clear(): void;
+}>;
+export declare function assertProductDiscussionConversationPreTask(options: {
+    conversationLocator: string;
+    listTaskIds(): readonly string[] | Promise<readonly string[]>;
+    getTaskRoleBindings(taskId: string): readonly ProductDiscussionTaskRoleBindingFact[] | Promise<readonly ProductDiscussionTaskRoleBindingFact[]>;
+}): Promise<void>;
+export declare function createProductDiscussionAdmissionCoordinator(options: {
+    productRoleRef: string;
+    authority: ReturnType<typeof createProductDiscussionAdmissionAuthority>;
+    isTaskWorkerProvisioning(roleRef: string): boolean;
+    listTaskIds(): readonly string[] | Promise<readonly string[]>;
+    getTaskRoleBindings(taskId: string): readonly ProductDiscussionTaskRoleBindingFact[] | Promise<readonly ProductDiscussionTaskRoleBindingFact[]>;
+    registerDiscussionSession(input: {
+        discussionRef: string;
+        roleRef: string;
+        conversationRef: string;
+        conversationLocator: string;
+    }): ProductDiscussionSessionOwnerFact | Promise<ProductDiscussionSessionOwnerFact>;
+    deliverBootstrap(admission: ProductDiscussionAdmission): void | Promise<void>;
+}): Readonly<{
+    observe: (input: {
+        conversationLocator: string;
+        contentInstanceId: string;
+    }) => Promise<Readonly<{
+        admitted: false;
+        reason: "NOT_CUSTOM_GPT_CONVERSATION";
+    }> | Readonly<{
+        admitted: false;
+        reason: "NOT_PRODUCT_ROLE";
+    }> | Readonly<{
+        admitted: true;
+        discussionRef: string;
+        discussionGeneration: number;
+        bootstrapRef: string;
+    }>>;
+}>;
+export {};