@agentxm/workspace-operations 0.28.4-bootstrap.0

package/dist/src/plan/errors.js

@@ -0,0 +1,101 @@
+/**
+ * Error category vocabulary for serialized plan and step data.
+ *
+ * The categories are the same strings as the CLI's `AppErrorCode` so machine
+ * output stays byte-identical across the package boundary; the conversion
+ * boundary beside the CLI error vocabulary asserts the parity at compile
+ * time. The kernel owns the vocabulary because plans, journals, and machine
+ * output serialize it; it never owns titles, exit codes, or rendering.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+/** Every category a plan, step result, or risk condition may serialize. */
+export const OPERATION_ERROR_CATEGORIES = [
+    "issues",
+    "usage",
+    "not_found",
+    "auth",
+    "forbidden",
+    "conflict",
+    "rate_limit",
+    "network",
+    "validation",
+    "internal",
+    "unavailable",
+    "quota",
+    "auth_required",
+    "auth_expired",
+    "auth_denied",
+    "timeout",
+];
+export const OperationErrorCategorySchema = Schema.Literals(OPERATION_ERROR_CATEGORIES).annotate({
+    identifier: "OperationErrorCategory",
+});
+/**
+ * The `SuggestedAction` contract shape, without the safe-command runtime
+ * filter: a step failure carries whatever suggestion its producer chose, and
+ * the CLI boundary sanitizes suggested commands before rendering them.
+ */
+const CarriedSuggestedActionSchema = Schema.Struct({
+    description: Schema.String,
+    cmd: Schema.optional(Schema.String),
+    url: Schema.optional(Schema.String),
+});
+const _suggestedActionParity = (value) => value;
+void _suggestedActionParity;
+/**
+ * The one serializable failure a plan step settles with. Step authors own the
+ * category choice and the user-facing detail sentence; `suggestions` carries
+ * only display data the boundary cannot reconstruct from fields, and `cause`
+ * carries the typed feature error or raw cause for diagnostic chains. The CLI
+ * boundary owns rendering, exit codes, and the AppError envelope.
+ */
+export class StepFailure extends Schema.TaggedError()("StepFailure", {
+    category: OperationErrorCategorySchema,
+    detail: Schema.String,
+    suggestions: Schema.optional(Schema.Array(CarriedSuggestedActionSchema)),
+    cause: Schema.optional(Schema.Unknown),
+}) {
+}
+/**
+ * Detail sentence for a stale execution candidate; the CLI conversion emits
+ * it verbatim so blocked output stays byte-identical.
+ */
+export const STALE_CANDIDATE_DETAIL = "The execution candidate became stale before apply.";
+/**
+ * The frozen execution candidate's material preimages changed between
+ * validation and apply. Detected by tag, never by detail-string comparison.
+ */
+export class StaleExecutionCandidate extends Schema.TaggedError()("StaleExecutionCandidate", {
+    /** The plan name of the candidate that went stale. */
+    candidate: Schema.String,
+}) {
+}
+/** Fingerprinting one execution-material path failed. */
+export class CandidateFingerprintFailed extends Schema.TaggedError()("CandidateFingerprintFailed", {
+    /** The material path whose preimage could not be read. */
+    target: Schema.String,
+    cause: Schema.Unknown,
+}) {
+}
+/**
+ * An apply-mode execution reached the plan pipeline without approval
+ * recovery metadata: a caller violated the `PlanExecution` contract. The CLI
+ * boundary owns the rendering.
+ */
+export class ApprovalRecoveryMissing extends Schema.TaggedError()("ApprovalRecoveryMissing", {}) {
+}
+/**
+ * The plan interaction implementation could not complete a presentation or
+ * confirmation exchange. The implementation owns wording and category choice;
+ * the kernel only transports the failure to the boundary that renders it.
+ */
+export class PlanInteractionFailed extends Schema.TaggedError()("PlanInteractionFailed", {
+    category: OperationErrorCategorySchema,
+    detail: Schema.String,
+    suggestions: Schema.optional(Schema.Array(CarriedSuggestedActionSchema)),
+    cause: Schema.optional(Schema.Unknown),
+}) {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/plan/execution-candidate.d.ts

@@ -0,0 +1,20 @@
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import { CandidateFingerprintFailed } from "./errors.js";
+import type { Plan } from "./plan.js";
+export interface ExecutionCandidate<Requirements = never, Output = never> {
+    readonly id: string;
+    readonly plan: Plan<Requirements, Output>;
+    readonly materialPaths: ReadonlyArray<string>;
+    readonly materialFingerprint: string;
+    /** Base the material fingerprint is relative to; freshness recomputes against it. */
+    readonly baseDir: string;
+}
+export declare const makeExecutionCandidate: <Requirements, Output>(plan: Plan<Requirements, Output>, paths: {
+    readonly settingsPath: string;
+    readonly lockPath: string;
+    readonly baseDir: string;
+}) => Effect.Effect<ExecutionCandidate<Requirements, Output>, CandidateFingerprintFailed, FileSystem.FileSystem | Path.Path>;
+export declare const isExecutionCandidateFresh: (candidate: ExecutionCandidate<unknown, unknown>) => Effect.Effect<boolean, CandidateFingerprintFailed, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=execution-candidate.d.ts.map

package/dist/src/plan/execution-candidate.js

@@ -0,0 +1,95 @@
+import * as crypto from "node:crypto";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { CandidateFingerprintFailed } from "./errors.js";
+const collectArtifactPaths = (plan) => plan.jobs.flatMap((job) => job.steps.flatMap((step) => {
+    if (step.artifact === undefined)
+        return [];
+    return [step.artifact.path, ...(step.artifact.targets ?? []).map((target) => target.path)];
+}));
+const resolveMaterialPaths = (plan, settingsPath, lockPath, baseDir, path) => Array.from(new Set([settingsPath, lockPath, ...(plan.materialPaths ?? []), ...collectArtifactPaths(plan)].map((candidate) => path.resolve(baseDir, candidate)))).sort();
+const fingerprintPath = (target, label, fs, path) => Effect.gen(function* () {
+    const link = yield* fs.readLink(target).pipe(Effect.option);
+    if (Option.isSome(link))
+        return [label, "symlink", link.value];
+    const info = yield* fs.stat(target).pipe(Effect.option);
+    if (Option.isNone(info))
+        return [label, "absent"];
+    if (info.value.type === "File")
+        return [label, "file", yield* fs.readFile(target)];
+    if (info.value.type !== "Directory")
+        return [label, info.value.type];
+    const entries = [...(yield* fs.readDirectory(target, { recursive: true }))].sort();
+    const parts = [label, "directory"];
+    for (const entry of entries) {
+        const absolute = path.join(target, entry);
+        const entryInfo = yield* fs.stat(absolute);
+        parts.push(entry, entryInfo.type);
+        if (entryInfo.type === "File")
+            parts.push(yield* fs.readFile(absolute));
+        if (entryInfo.type === "SymbolicLink")
+            parts.push(yield* fs.readLink(absolute));
+    }
+    return parts;
+}).pipe(Effect.mapError((cause) => new CandidateFingerprintFailed({ target, cause })));
+// Materials hash under their base-relative names: candidate identity is a
+// property of workspace content, not of where the workspace sits on disk.
+const fingerprintMaterials = (materialPaths, baseDir, fs, path) => Effect.gen(function* () {
+    const hash = crypto.createHash("sha256");
+    for (const target of materialPaths) {
+        const parts = yield* fingerprintPath(target, path.relative(baseDir, target), fs, path);
+        for (const part of parts) {
+            hash.update(part);
+            hash.update("\0");
+        }
+    }
+    return hash.digest("hex");
+});
+// Absolute paths inside plan metadata relativize before hashing: candidate
+// identity is a property of workspace content, not of where it sits on disk.
+const planIdentity = (plan, baseDir, path) => JSON.stringify({
+    name: plan.name,
+    jobs: plan.jobs.map((job) => ({
+        concurrency: job.concurrency,
+        executionPolicy: job.executionPolicy,
+        steps: job.steps.map((step) => ({
+            key: step.key,
+            dependsOn: step.dependsOn,
+            label: step.label,
+            readiness: step.readiness,
+            artifact: step.artifact,
+            registryLifecycle: step.registryLifecycle,
+        })),
+    })),
+    preconditions: plan.preconditions,
+    riskConditions: plan.riskConditions,
+    releaseAge: plan.releaseAge,
+}, (key, value) => {
+    if (key === "evaluatedAt")
+        return undefined;
+    return typeof value === "string" && path.isAbsolute(value)
+        ? path.relative(baseDir, value)
+        : value;
+});
+export const makeExecutionCandidate = (plan, paths) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const materialPaths = resolveMaterialPaths(plan, paths.settingsPath, paths.lockPath, paths.baseDir, path);
+    const materialFingerprint = yield* fingerprintMaterials(materialPaths, paths.baseDir, fs, path);
+    const id = crypto
+        .createHash("sha256")
+        .update(planIdentity(plan, paths.baseDir, path))
+        .update("\0")
+        .update(materialFingerprint)
+        .digest("hex");
+    return { id, plan, materialPaths, materialFingerprint, baseDir: paths.baseDir };
+});
+export const isExecutionCandidateFresh = (candidate) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const current = yield* fingerprintMaterials(candidate.materialPaths, candidate.baseDir, fs, path);
+    return current === candidate.materialFingerprint;
+});
+//# sourceMappingURL=execution-candidate.js.map

package/dist/src/plan/interruption-signal.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Interruption-signal source port.
+ *
+ * The process-entry adapter records which signal requested termination; the
+ * kernel reads that fact through this port when it resolves an interrupted
+ * apply. When no source is provided, the kernel assumes SIGINT.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+export interface InterruptionSignalSourceService {
+    readonly requestedSignal: () => "SIGINT" | "SIGTERM" | undefined;
+}
+declare const InterruptionSignalSource_base: ServiceMap.ServiceClass<InterruptionSignalSource, "@agentxm/workspace-operations/plan/interruption-signal/InterruptionSignalSource", InterruptionSignalSourceService>;
+export declare class InterruptionSignalSource extends InterruptionSignalSource_base {
+}
+export {};
+//# sourceMappingURL=interruption-signal.d.ts.map

package/dist/src/plan/interruption-signal.js

@@ -0,0 +1,13 @@
+/**
+ * Interruption-signal source port.
+ *
+ * The process-entry adapter records which signal requested termination; the
+ * kernel reads that fact through this port when it resolves an interrupted
+ * apply. When no source is provided, the kernel assumes SIGINT.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+export class InterruptionSignalSource extends ServiceMap.Service()("@agentxm/workspace-operations/plan/interruption-signal/InterruptionSignalSource") {
+}
+//# sourceMappingURL=interruption-signal.js.map

package/dist/src/plan/job-step-message.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Job-step message helpers.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const appendWarningsToMessage: (message: string, warnings: ReadonlyArray<string>) => string;
+//# sourceMappingURL=job-step-message.d.ts.map

package/dist/src/plan/job-step-message.js

@@ -0,0 +1,7 @@
+/**
+ * Job-step message helpers.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const appendWarningsToMessage = (message, warnings) => (warnings.length === 0 ? message : `${message}; ${warnings.join("; ")}`);
+//# sourceMappingURL=job-step-message.js.map

package/dist/src/plan/operation-events.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Operation lifecycle events.
+ *
+ * Execution publishes typed lifecycle events — phase transitions, unit state
+ * transitions, and waiting reasons, each with a monotonic timestamp — to an
+ * invocation-scoped broadcast. Observers (renderers, machine progress,
+ * telemetry) subscribe; none of them controls execution or keeps a second
+ * account of what happened. Publishing is a no-op when no broadcast is
+ * provided.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as PubSub from "effect/PubSub";
+import type * as Scope from "effect/Scope";
+import * as ServiceMap from "effect/Context";
+import type { BlockingClass } from "./plan.js";
+import type { OperationPhase, UnitState } from "./operation-resolution.js";
+export type OperationLifecycleEvent = {
+    readonly _tag: "PhaseStarted";
+    readonly phase: OperationPhase;
+    readonly atNanos: bigint;
+} | {
+    readonly _tag: "UnitStarted";
+    readonly unitId: string;
+    readonly label: string;
+    readonly index: number;
+    readonly total: number;
+    readonly atNanos: bigint;
+} | {
+    readonly _tag: "UnitResolved";
+    readonly unitId: string;
+    readonly label: string;
+    readonly state: UnitState;
+    readonly index: number;
+    readonly total: number;
+    readonly atNanos: bigint;
+} | {
+    readonly _tag: "Waiting";
+    readonly blockingClass: BlockingClass;
+    readonly subject: string;
+    readonly detail: string;
+    readonly atNanos: bigint;
+};
+export interface OperationLifecycleService {
+    readonly mode: "preview" | "apply";
+    readonly pubsub: PubSub.PubSub<OperationLifecycleEvent>;
+}
+declare const OperationLifecycle_base: ServiceMap.ServiceClass<OperationLifecycle, "@agentxm/workspace-operations/plan/operation-events/OperationLifecycle", OperationLifecycleService>;
+export declare class OperationLifecycle extends OperationLifecycle_base {
+}
+/** Publish one lifecycle event. No-op when no broadcast is provided. */
+export declare const publishLifecycleEvent: (make: (atNanos: bigint) => OperationLifecycleEvent) => Effect.Effect<void>;
+export declare const publishPhaseStarted: (phase: OperationPhase) => Effect.Effect<void>;
+/**
+ * Fork a subscriber that observes every lifecycle event published while the
+ * scope lives. No-op (returns immediately) when no broadcast is provided.
+ */
+export declare const subscribeToLifecycle: (observe: (event: OperationLifecycleEvent) => Effect.Effect<void>) => Effect.Effect<void, never, Scope.Scope>;
+export declare const makeOperationLifecycle: (mode: "preview" | "apply") => Effect.Effect<OperationLifecycleService>;
+export {};
+//# sourceMappingURL=operation-events.d.ts.map

package/dist/src/plan/operation-events.js

@@ -0,0 +1,41 @@
+/**
+ * Operation lifecycle events.
+ *
+ * Execution publishes typed lifecycle events — phase transitions, unit state
+ * transitions, and waiting reasons, each with a monotonic timestamp — to an
+ * invocation-scoped broadcast. Observers (renderers, machine progress,
+ * telemetry) subscribe; none of them controls execution or keeps a second
+ * account of what happened. Publishing is a no-op when no broadcast is
+ * provided.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as ServiceMap from "effect/Context";
+export class OperationLifecycle extends ServiceMap.Service()("@agentxm/workspace-operations/plan/operation-events/OperationLifecycle") {
+}
+/** Publish one lifecycle event. No-op when no broadcast is provided. */
+export const publishLifecycleEvent = (make) => Effect.gen(function* () {
+    const service = yield* Effect.serviceOption(OperationLifecycle);
+    if (Option.isNone(service))
+        return;
+    const atNanos = yield* Clock.currentTimeNanos;
+    yield* PubSub.publish(service.value.pubsub, make(atNanos));
+});
+export const publishPhaseStarted = (phase) => publishLifecycleEvent((atNanos) => ({ _tag: "PhaseStarted", phase, atNanos }));
+/**
+ * Fork a subscriber that observes every lifecycle event published while the
+ * scope lives. No-op (returns immediately) when no broadcast is provided.
+ */
+export const subscribeToLifecycle = (observe) => Effect.gen(function* () {
+    const service = yield* Effect.serviceOption(OperationLifecycle);
+    if (Option.isNone(service))
+        return;
+    const subscription = yield* PubSub.subscribe(service.value.pubsub);
+    yield* Effect.forkScoped(Effect.forever(PubSub.take(subscription).pipe(Effect.flatMap(observe))));
+});
+export const makeOperationLifecycle = (mode) => PubSub.unbounded().pipe(Effect.map((pubsub) => ({ mode, pubsub })));
+//# sourceMappingURL=operation-events.js.map

package/dist/src/plan/operation-journal.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Operation journal — the invocation-scoped record of a plan-family
+ * operation's progress.
+ *
+ * The resolution boundary writes the frozen candidate's facts at planning,
+ * records each phase transition, and records per-unit started and resolved
+ * facts as execution reaches them — settlement is recorded before the next
+ * interruptible boundary. When an external termination request interrupts the
+ * invocation, the lifecycle wrapper reads this journal to resolve the
+ * interruption truthfully: which units settled, which were in flight, which
+ * were never attempted, and what the durable-state disposition of each is.
+ * The journal is invocation-local; nothing here persists past the process.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as ServiceMap from "effect/Context";
+import type { CompletedJobStep, OperationPresentation, PlanRiskCondition } from "./plan.js";
+import type { ReleaseAgeOperationEvidence } from "@agentxm/registry-protocol/unstable/registry/release-age-policy";
+import type { OperationPrecondition } from "./plan.js";
+import type { OperationAtomicity, OperationPhase, ResolvedUnit } from "./operation-resolution.js";
+export interface OperationJournalState {
+    readonly name: string;
+    readonly description: Option.Option<string>;
+    readonly mode: "preview" | "apply";
+    readonly candidateId?: string;
+    readonly atomicity: OperationAtomicity;
+    readonly presentation?: OperationPresentation;
+    readonly releaseAge?: ReleaseAgeOperationEvidence;
+    readonly preconditions?: ReadonlyArray<OperationPrecondition>;
+    readonly riskConditions?: ReadonlyArray<PlanRiskCondition>;
+    /** Units of the frozen candidate, in planned states. */
+    readonly plannedUnits: ReadonlyArray<ResolvedUnit<unknown>>;
+    /** The lifecycle phase the invocation had reached when last recorded. */
+    readonly phase: OperationPhase;
+    /** Ids of units whose run began, in start order. */
+    readonly startedUnitIds: ReadonlyArray<string>;
+    /**
+     * Settlement facts, recorded the moment each unit resolved — before any
+     * interruptible boundary — in execution order. A started unit missing here
+     * is in flight: its durable effects are restored by the closure's rollback
+     * or unknown, never "not attempted".
+     */
+    readonly resolved: ReadonlyArray<CompletedJobStep<unknown>>;
+    /** True while the apply runs inside a restoring (closure-atomic) guard. */
+    readonly restoresOnFailure: boolean;
+}
+export interface OperationJournalService {
+    readonly ref: Ref.Ref<Option.Option<OperationJournalState>>;
+}
+declare const OperationJournal_base: ServiceMap.ServiceClass<OperationJournal, "@agentxm/workspace-operations/plan/operation-journal/OperationJournal", OperationJournalService>;
+export declare class OperationJournal extends OperationJournal_base {
+}
+/** Record the operation's frozen facts. No-op when no journal is provided. */
+export declare const recordOperationJournal: (state: OperationJournalState) => Effect.Effect<void>;
+/** Merge updates onto the recorded state. No-op when nothing was recorded. */
+export declare const updateOperationJournal: (update: (state: OperationJournalState) => OperationJournalState) => Effect.Effect<void>;
+/** Record the lifecycle phase the invocation has entered. */
+export declare const recordJournalPhase: (phase: OperationPhase) => Effect.Effect<void>;
+/** Record that a unit's run began. */
+export declare const appendStartedUnit: (unitId: string) => Effect.Effect<void>;
+/** Record one unit's settlement fact. */
+export declare const appendResolvedUnit: (step: CompletedJobStep<unknown>) => Effect.Effect<void>;
+export declare const getOperationJournal: Effect.Effect<Option.Option<OperationJournalState>>;
+export declare const makeOperationJournal: Effect.Effect<OperationJournalService>;
+export {};
+//# sourceMappingURL=operation-journal.d.ts.map

package/dist/src/plan/operation-journal.js

@@ -0,0 +1,52 @@
+/**
+ * Operation journal — the invocation-scoped record of a plan-family
+ * operation's progress.
+ *
+ * The resolution boundary writes the frozen candidate's facts at planning,
+ * records each phase transition, and records per-unit started and resolved
+ * facts as execution reaches them — settlement is recorded before the next
+ * interruptible boundary. When an external termination request interrupts the
+ * invocation, the lifecycle wrapper reads this journal to resolve the
+ * interruption truthfully: which units settled, which were in flight, which
+ * were never attempted, and what the durable-state disposition of each is.
+ * The journal is invocation-local; nothing here persists past the process.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as ServiceMap from "effect/Context";
+export class OperationJournal extends ServiceMap.Service()("@agentxm/workspace-operations/plan/operation-journal/OperationJournal") {
+}
+/** Record the operation's frozen facts. No-op when no journal is provided. */
+export const recordOperationJournal = (state) => Effect.gen(function* () {
+    const service = yield* Effect.serviceOption(OperationJournal);
+    if (Option.isNone(service))
+        return;
+    yield* Ref.set(service.value.ref, Option.some(state));
+});
+/** Merge updates onto the recorded state. No-op when nothing was recorded. */
+export const updateOperationJournal = (update) => Effect.gen(function* () {
+    const service = yield* Effect.serviceOption(OperationJournal);
+    if (Option.isNone(service))
+        return;
+    yield* Ref.update(service.value.ref, Option.map(update));
+});
+/** Record the lifecycle phase the invocation has entered. */
+export const recordJournalPhase = (phase) => updateOperationJournal((state) => ({ ...state, phase }));
+/** Record that a unit's run began. */
+export const appendStartedUnit = (unitId) => updateOperationJournal((state) => ({
+    ...state,
+    startedUnitIds: [...state.startedUnitIds, unitId],
+}));
+/** Record one unit's settlement fact. */
+export const appendResolvedUnit = (step) => updateOperationJournal((state) => ({ ...state, resolved: [...state.resolved, step] }));
+export const getOperationJournal = Effect.gen(function* () {
+    const service = yield* Effect.serviceOption(OperationJournal);
+    if (Option.isNone(service))
+        return Option.none();
+    return yield* Ref.get(service.value.ref);
+});
+export const makeOperationJournal = Ref.make(Option.none()).pipe(Effect.map((ref) => ({ ref })));
+//# sourceMappingURL=operation-journal.js.map