@agentxm/workspace-operations 0.29.2 → 0.30.1

package/dist/src/index.d.ts

@@ -11,8 +11,8 @@
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
-export { BlockingClassSchema, defaultOperationPresentation, operationPresentation, presentationOf, ArtifactMechanismSchema, ConfirmableConsentSchema, OperationPreconditionSchema, PlanPolicyIdSchema, PlanPolicyIds, PlanRiskConditionSchema, } from "./plan/plan.js";
-export type { ArtifactMechanism, BlockingClass, CompletedJobStep, ConfirmableConsent, ErrorJobStep, ExecutedJob, ExecutedPlan, Job, JobStepArtifact, JobStepArtifactSource, JobStepArtifactTarget, JobStepResult, Operation, OperationPrecondition, OperationPresentation, Plan, PlanExecutionCapabilities, PlanPolicyId, PlanRiskCondition, PlannedJobStep, ReadyJobStep, RegistryLifecycleEvidence, UnitBlocking, WarnJobStep, } from "./plan/plan.js";
+export { BlockingClassSchema, defaultOperationPresentation, operationPresentation, presentationOf, ArtifactMechanismSchema, PackMembershipDeltaSchema, ConfirmableConsentSchema, OperationPreconditionSchema, PlanPolicyIdSchema, PlanPolicyIds, PlanRiskConditionSchema, } from "./plan/plan.js";
+export type { ArtifactMechanism, BlockingClass, CompletedJobStep, ConfirmableConsent, ErrorJobStep, ExecutedJob, ExecutedPlan, Job, JobStepArtifact, PackMembershipDelta, JobStepArtifactSource, JobStepArtifactTarget, JobStepArtifactReference, JobStepResult, Operation, OperationPrecondition, OperationPresentation, Plan, PlanExecutionCapabilities, PlanPolicyId, PlanRiskCondition, PlannedJobStep, ReadyJobStep, RegistryLifecycleEvidence, UnitBlocking, WarnJobStep, } from "./plan/plan.js";
 export { AtomicityClassSchema, OperationOutcomeSchema, OperationPhaseSchema, UnitDispositionSchema, UnitStateSchema, countUnitStates, declaredAtomicity, deriveOperationOutcome, executedUnits, makeOperationResolution, plannedUnits, unitIdOf, unitsByStableIdentity, } from "./plan/operation-resolution.js";
 export type { AtomicityClass, MakeOperationResolutionArgs, OperationAtomicity, OperationBlock, OperationFootprintEntry, OperationInterruption, OperationOutcome, OperationPhase, OperationRecovery, OperationResolution, ResolvedUnit, UnitDisposition, UnitState, UnitStateCounts, } from "./plan/operation-resolution.js";
 export { OperationJournal, appendResolvedUnit, appendStartedUnit, recordJournalPhase, getOperationJournal, makeOperationJournal, recordOperationJournal, updateOperationJournal, type OperationJournalService, type OperationJournalState, } from "./plan/operation-journal.js";

package/dist/src/index.js

@@ -12,7 +12,7 @@
  * @packageDocumentation
  */
 // Plan types
-export { BlockingClassSchema, defaultOperationPresentation, operationPresentation, presentationOf, ArtifactMechanismSchema, ConfirmableConsentSchema, OperationPreconditionSchema, PlanPolicyIdSchema, PlanPolicyIds, PlanRiskConditionSchema, } from "./plan/plan.js";
+export { BlockingClassSchema, defaultOperationPresentation, operationPresentation, presentationOf, ArtifactMechanismSchema, PackMembershipDeltaSchema, ConfirmableConsentSchema, OperationPreconditionSchema, PlanPolicyIdSchema, PlanPolicyIds, PlanRiskConditionSchema, } from "./plan/plan.js";
 // Operation resolution — the single value every plan-family command
 // terminates with, with its pure outcome derivations.
 export { AtomicityClassSchema, OperationOutcomeSchema, OperationPhaseSchema, UnitDispositionSchema, UnitStateSchema, countUnitStates, declaredAtomicity, deriveOperationOutcome, executedUnits, makeOperationResolution, plannedUnits, unitIdOf, unitsByStableIdentity, } from "./plan/operation-resolution.js";

package/dist/src/plan/apply-plan.d.ts

@@ -23,9 +23,9 @@ export type OperationHandler<Op, R = never> = (op: Op) => Effect.Effect<JobStepR
 /**
  * Apply a plan by iterating jobs and executing step run closures.
  *
- * Any readiness error gates the complete plan before execution. At runtime,
- * jobs use ordered fail-fast execution by default. A job may explicitly opt
- * into best-effort execution for independent siblings; failures still block
+ * Readiness errors in ordered jobs gate the complete plan. A job may explicitly
+ * opt into best-effort execution for independent siblings, including siblings
+ * blocked during preparation. Runtime failures still block
  * all subsequent jobs.
  *
  * Never fails — catches StepFailure and converts to error results.

package/dist/src/plan/apply-plan.js

@@ -36,19 +36,9 @@ const stepEvidence = (step) => ({
 const executeStep = (step) => {
     switch (step.readiness) {
         case "error":
-            return Effect.succeed({
-                ...(step.key === undefined ? {} : { key: step.key }),
-                ...stepEvidence(step),
-                label: step.label,
-                result: {
-                    result: "error",
-                    message: step.errorMessage,
-                    error: new StepFailure({
-                        category: "internal",
-                        detail: step.errorMessage,
-                    }),
-                },
-            });
+            return Effect.succeed(blockStep(step, step.errorMessage, {
+                class: "precondition-unmet",
+            }));
         case "ready":
             return step.run.pipe(Effect.map((result) => ({
                 ...(step.key === undefined ? {} : { key: step.key }),
@@ -202,7 +192,8 @@ const executeDependencyAwareJob = (job, observeStart, observeStep) => Effect.gen
 export const applyPlan = (plan, options) => Effect.gen(function* () {
     const observeStep = options?.onStepCompleted ?? (() => Effect.void);
     const observeStart = options?.onStepStarted ?? (() => Effect.void);
-    const hasReadinessError = plan.jobs.some((job) => job.steps.some((step) => step.readiness === "error"));
+    const hasReadinessError = plan.jobs.some((job) => job.executionPolicy !== "best-effort" &&
+        job.steps.some((step) => step.readiness === "error"));
     // Any job with an error blocks every later job; the fact travels in a
     // `Ref` because it crosses the job traversal's iteration boundary.
     const blocked = yield* Ref.make(false);

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

@@ -6,8 +6,14 @@ 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)];
+        return step.materialPaths ?? [];
+    return [
+        ...(step.materialPaths ?? []),
+        step.artifact.path,
+        ...(step.artifact.targets ?? []).map((target) => target.path),
+        ...(step.artifact.references ?? []).map((reference) => reference.path),
+        ...(step.artifact.managedRegions ?? []).map((region) => region.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* () {
@@ -57,6 +63,7 @@ const planIdentity = (plan, baseDir, path) => JSON.stringify({
         steps: job.steps.map((step) => ({
             key: step.key,
             dependsOn: step.dependsOn,
+            materialPaths: step.materialPaths,
             label: step.label,
             readiness: step.readiness,
             artifact: step.artifact,

package/dist/src/plan/plan.d.ts

@@ -76,6 +76,24 @@ export interface Operation<TName extends string, TArgs> {
 }
 export declare const ArtifactMechanismSchema: Schema.Literals<readonly ["symlink", "copy"]>;
 export type ArtifactMechanism = typeof ArtifactMechanismSchema.Type;
+/** Resolved manifest changes; null denotes an absent dependency. */
+export declare const PackMembershipDeltaSchema: Schema.Struct<{
+    readonly pack: Schema.String;
+    readonly members: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly member: Schema.String;
+        readonly before: Schema.Null;
+        readonly after: Schema.String;
+    }>, Schema.Struct<{
+        readonly member: Schema.String;
+        readonly before: Schema.String;
+        readonly after: Schema.Null;
+    }>, Schema.Struct<{
+        readonly member: Schema.String;
+        readonly before: Schema.String;
+        readonly after: Schema.String;
+    }>]>>;
+}>;
+export type PackMembershipDelta = typeof PackMembershipDeltaSchema.Type;
 export interface JobStepArtifact {
     readonly path: string;
     readonly scope: "project" | "user";
@@ -86,9 +104,12 @@ export interface JobStepArtifact {
     readonly previousVersion?: string;
     readonly fileCount?: number;
     readonly targets?: ReadonlyArray<JobStepArtifactTarget>;
+    /** Observed retained, absent, or unresolved state; these are not write targets. */
+    readonly references?: ReadonlyArray<JobStepArtifactReference>;
     readonly agentOutcomes?: ReadonlyArray<ConfiguredAgentOutcome>;
     readonly source?: JobStepArtifactSource;
     readonly managedRegions?: ReadonlyArray<JobStepManagedRegion>;
+    readonly packMembership?: PackMembershipDelta;
     /** Registry lifecycle evidence captured when the candidate was resolved. */
     readonly registryLifecycle?: {
         readonly deprecation: DeprecationView;
@@ -99,10 +120,20 @@ export interface JobStepManagedRegion {
     readonly path: string;
     readonly owner: string;
 }
+export interface JobStepArtifactReference {
+    readonly path: string;
+    readonly state: "retained" | "absent" | "unknown";
+    readonly reason: string;
+    readonly unitId?: string;
+    readonly owner?: string;
+}
 export interface JobStepArtifactTarget {
     readonly path: string;
     readonly change: ArtifactChange;
     readonly agentIds?: ReadonlyArray<string>;
+    readonly unitId?: string;
+    readonly owner?: string;
+    readonly entryName?: string;
 }
 export interface JobStepArtifactSource {
     readonly type: string;
@@ -135,6 +166,8 @@ export type JobStepResult<Output = never> = {
 export interface ReadyJobStep<Requirements = never, Output = never> {
     readonly key?: string;
     readonly dependsOn?: ReadonlyArray<string>;
+    /** Read-only inputs fingerprinted with this step, distinct from its write footprint. */
+    readonly materialPaths?: ReadonlyArray<string>;
     readonly readiness: "ready";
     readonly label: string;
     readonly message?: string;
@@ -147,6 +180,8 @@ export interface ReadyJobStep<Requirements = never, Output = never> {
 export interface WarnJobStep<Requirements = never, Output = never> {
     readonly key?: string;
     readonly dependsOn?: ReadonlyArray<string>;
+    /** Read-only inputs fingerprinted with this step, distinct from its write footprint. */
+    readonly materialPaths?: ReadonlyArray<string>;
     readonly readiness: "warn";
     readonly warnMessage: string;
     readonly label: string;
@@ -159,6 +194,8 @@ export interface WarnJobStep<Requirements = never, Output = never> {
 export interface ErrorJobStep {
     readonly key?: string;
     readonly dependsOn?: ReadonlyArray<string>;
+    /** Read-only inputs fingerprinted with this step, distinct from its write footprint. */
+    readonly materialPaths?: ReadonlyArray<string>;
     readonly readiness: "error";
     readonly errorMessage: string;
     readonly label: string;
@@ -184,7 +221,8 @@ export interface Job<Requirements = never, Output = never> {
     readonly concurrency: "unbounded" | number;
     /**
      * Defaults to ordered fail-fast execution. Use `best-effort` only when every
-     * sibling step is independent; a failure still blocks subsequent jobs.
+     * sibling step is independent, including readiness failures; a failure still
+     * blocks subsequent jobs.
      */
     readonly executionPolicy?: JobExecutionPolicy;
 }

package/dist/src/plan/plan.js

@@ -72,6 +72,15 @@ export const PlanRiskConditionSchema = Schema.Union([
 // Step result types
 // -----------------------------------------------------------------------------
 export const ArtifactMechanismSchema = Schema.Literals(["symlink", "copy"]);
+/** Resolved manifest changes; null denotes an absent dependency. */
+export const PackMembershipDeltaSchema = Schema.Struct({
+    pack: Schema.String,
+    members: Schema.Array(Schema.Union([
+        Schema.Struct({ member: Schema.String, before: Schema.Null, after: Schema.String }),
+        Schema.Struct({ member: Schema.String, before: Schema.String, after: Schema.Null }),
+        Schema.Struct({ member: Schema.String, before: Schema.String, after: Schema.String }),
+    ])),
+});
 /** Presentation for an operation on one extension type (or extensions generally). */
 export const operationPresentation = (verb, type) => ({
     verb,

package/dist/src/plan/resolve-plan.js

@@ -108,7 +108,10 @@ const outcomesFor = (ws, provider, configuredAgents, operation, state) => {
 /** The readiness blockers a plan's error steps contribute beyond declared conditions. */
 const readinessBlockersOf = (plan) => {
     const declaredConditionIds = new Set((plan.riskConditions ?? []).map((condition) => condition.id));
-    return plan.jobs.flatMap((job) => job.steps.flatMap((step) => step.readiness === "error"
+    const hasRunnable = plan.jobs.some((job) => job.steps.some((step) => step.readiness !== "error"));
+    return plan.jobs
+        .filter((job) => !hasRunnable || job.executionPolicy !== "best-effort")
+        .flatMap((job) => job.steps.flatMap((step) => step.readiness === "error"
         ? (step.blockingConditionIds ?? []).length > 0 &&
             (step.blockingConditionIds ?? []).every((id) => declaredConditionIds.has(id))
             ? []
@@ -193,7 +196,10 @@ export const resolveExecutionCandidate = Effect.fn("resolveExecutionCandidate")(
     const candidatePlan = candidate.plan;
     const operations = candidate.configuredAgentOperations;
     const configuredAgents = operations.length === 0 ? [] : yield* ws.getConfiguredAgents();
-    const readiness = scanPlanReadiness(candidatePlan);
+    const readiness = scanPlanReadiness({
+        ...candidatePlan,
+        jobs: candidatePlan.jobs.filter((job) => job.executionPolicy !== "best-effort"),
+    });
     const readinessBlockers = readinessBlockersOf(candidatePlan);
     const riskConditions = candidatePlan.riskConditions ?? [];
     const atomicity = declaredAtomicity(candidatePlan);

package/package.json

@@ -4,36 +4,33 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/extension-model": "^0.29.2",
-    "@agentxm/extension-resolution": "^0.29.2",
-    "@agentxm/registry-protocol": "^0.29.2",
-    "@agentxm/workspace-state": "^0.29.2",
-    "@agentxm/workspace-transactions": "^0.29.2",
+    "@agentxm/extension-model": "^0.30.1",
+    "@agentxm/extension-resolution": "^0.30.1",
+    "@agentxm/registry-protocol": "^0.30.1",
+    "@agentxm/workspace-state": "^0.30.1",
+    "@agentxm/workspace-transactions": "^0.30.1",
     "effect": "4.0.0-rc.115"
   },
   "description": "AXM workspace operations: plans, execution candidates, closure execution, and operation resolutions for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
   "devDependencies": {
-    "@agentxm/specification-metadata": "^0.29.2",
+    "@agentxm/specification-metadata": "^0.30.1",
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/vitest": "4.0.0-rc.115",
     "@typescript/native": "npm:typescript@^7.0.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vitest": "^5.0.0",
-    "yaml": "^2.9.0"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22.19.0"
   },
   "exports": {
     ".": {
-      "axm-source": "./src/index.ts",
-      "default": "./dist/src/index.js",
-      "types": "./dist/src/index.d.ts"
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
     },
     "./testing": {
-      "axm-source": "./src/testing.ts",
-      "default": "./dist/src/testing.js",
-      "types": "./dist/src/testing.d.ts"
+      "types": "./dist/src/testing.d.ts",
+      "default": "./dist/src/testing.js"
     }
   },
   "files": [
@@ -56,5 +53,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.29.2"
+  "version": "0.30.1"
 }