@agentxm/extension-resolution 0.28.14-preview.1789139351.5cd4595aa

package/dist/src/release-age-policy.js

@@ -0,0 +1,115 @@
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { matchesReleaseAgeExcludePattern } from "@agentxm/extension-model/unstable/extensions/fqn-pattern";
+export const releaseAgeExemptionForIdentity = (evaluation, identity) => {
+    if (evaluation.grantedExemption !== undefined)
+        return evaluation.grantedExemption;
+    const excluded = evaluation.exclude?.find(({ pattern }) => matchesReleaseAgeExcludePattern(pattern, identity));
+    if (excluded !== undefined) {
+        return { bypassCause: "exclude", exemptionScope: excluded.scope };
+    }
+    return evaluation.mode === "ignore" ? { bypassCause: "ignore-flag" } : undefined;
+};
+const releaseAgeRecordKey = (record) => [
+    record.target,
+    ...record.dependencyPath,
+    record.candidateVersion,
+    record.selectedVersion ?? "",
+    record.currentVersion ?? "",
+    record.requestedRange ?? "",
+    "bypassCause" in record ? record.bypassCause : "",
+    "exemptionScope" in record ? record.exemptionScope : "",
+].join("\u0000");
+/** Deduplicate and order operation evidence independently from concurrent resolution order. */
+export const normalizeReleaseAgeRecords = (records) => {
+    const byKey = new Map();
+    for (const record of records) {
+        byKey.set(releaseAgeRecordKey(record), record);
+    }
+    return [...byKey.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([, record]) => record);
+};
+/**
+ * Documented exception: hand-rolled parser for the compact duration grammar
+ * (`24h`, `30d`, `500ms`).
+ *
+ * Effect v4 has no `Duration.decode`; the closest constructors are
+ * `Duration.fromInput` / `Duration.fromInputUnsafe`, and the `Duration.Input`
+ * string form only accepts space-separated long-unit strings ("30 days"), so
+ * the compact grammar is not expressible upstream. `durationPattern` and
+ * `parseMinimumReleaseAge` therefore stay as a thin syntax adapter over the
+ * `Duration` constructors (`Duration.millis` / `seconds` / `minutes` /
+ * `hours` / `days`).
+ *
+ * Removal condition: upstream `Duration` accepting the compact unit grammar.
+ */
+const durationPattern = /^(\d+)(ms|s|m|h|d)$/;
+export const parseMinimumReleaseAge = (value) => {
+    const trimmed = value.trim();
+    const match = durationPattern.exec(trimmed);
+    if (match === null)
+        return Option.none();
+    const amountText = match[1];
+    const unit = match[2];
+    if (amountText === undefined || unit === undefined)
+        return Option.none();
+    const amount = Number(amountText);
+    if (!Number.isSafeInteger(amount))
+        return Option.none();
+    switch (unit) {
+        case "ms":
+            return Option.some(Duration.millis(amount));
+        case "s":
+            return Option.some(Duration.seconds(amount));
+        case "m":
+            return Option.some(Duration.minutes(amount));
+        case "h":
+            return Option.some(Duration.hours(amount));
+        case "d":
+            return Option.some(Duration.days(amount));
+    }
+    // Unreachable at runtime, but `unit` is typed `string` (a regex capture),
+    // so the switch is not statically exhaustive and the compiler (TS2366)
+    // requires this ending return.
+    return Option.none();
+};
+/**
+ * Render a release-age window in the compact grammar the setting accepts, so
+ * output names the policy in the same units the reader would configure.
+ *
+ * Days are used only from two days up: the default window is written `24h`,
+ * and reporting it as `1d` would not match the setting the reader would edit.
+ * Falls back to whole seconds when the window is not a clean larger unit.
+ */
+export const formatMinimumReleaseAgeSeconds = (seconds) => {
+    const whole = Math.max(0, Math.round(seconds));
+    if (whole === 0)
+        return "0s";
+    if (whole % 86_400 === 0 && whole >= 172_800)
+        return `${whole / 86_400}d`;
+    if (whole % 3_600 === 0)
+        return `${whole / 3_600}h`;
+    if (whole % 60 === 0)
+        return `${whole / 60}m`;
+    return `${whole}s`;
+};
+export const isVersionEntryMature = (entry, minimumAge) => Duration.isLessThanOrEqualTo(minimumAge, Duration.zero)
+    ? Effect.succeed(true)
+    : DateTime.now.pipe(Effect.map((now) => 
+    // Inclusive at the boundary: a release published exactly `minimumAge`
+    // ago is mature, matching the original `now - published >= minimumAge`.
+    DateTime.isLessThanOrEqualTo(DateTime.addDuration(entry.published, minimumAge), now)));
+export const isVersionEntryEligibleAt = (entry, evaluation) => Duration.isLessThanOrEqualTo(evaluation.minimumReleaseAge, Duration.zero) ||
+    DateTime.isLessThanOrEqualTo(DateTime.addDuration(entry.published, evaluation.minimumReleaseAge), evaluation.evaluatedAt);
+export const releaseAgeEvidence = (entry, evaluation) => ({
+    version: entry.version,
+    publishedAt: DateTime.formatIso(entry.published),
+    eligibleAt: DateTime.formatIso(DateTime.addDuration(entry.published, evaluation.minimumReleaseAge)),
+    minimumReleaseAgeSeconds: Math.max(0, Duration.toMillis(evaluation.minimumReleaseAge) / 1_000),
+});
+export const filterMatureVersions = (versions, minimumAge) => Effect.filter(versions, (entry) => isVersionEntryMature(entry, minimumAge));
+export const releaseAgeHoldbackWarning = (args) => `${args.fqn} held at ${args.selectedVersion} — ${args.heldVersion} has not reached the ${args.minimumReleaseAge} minimum release age`;
+//# sourceMappingURL=release-age-policy.js.map

package/dist/src/release-age-posture.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The minimum-release-age gate's posture for one invocation.
+ *
+ * A leaf cannot invent this value: `makeConfiguredReleaseAgeEvaluation` reads
+ * it from context, so every gated code path carries the requirement up to the
+ * command boundary that owns the operator's decision. A command is
+ * gate-blockable precisely when its execution requests this service, which is
+ * what the conformance specification reads instead of a hand-copied list.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+/**
+ * `"enforce"` withholds a candidate that has not reached the configured
+ * minimum release age; `"ignore"` takes it for this run only. Neither value
+ * changes settings, and a declared exemption outranks both.
+ */
+export type ReleaseAgePostureValue = "enforce" | "ignore";
+declare const ReleaseAgePosture_base: ServiceMap.ServiceClass<ReleaseAgePosture, "axm.sh/extension-resolution/ReleaseAgePosture", ReleaseAgePostureValue>;
+export declare class ReleaseAgePosture extends ReleaseAgePosture_base {
+}
+export {};
+//# sourceMappingURL=release-age-posture.d.ts.map

package/dist/src/release-age-posture.js

@@ -0,0 +1,15 @@
+/**
+ * The minimum-release-age gate's posture for one invocation.
+ *
+ * A leaf cannot invent this value: `makeConfiguredReleaseAgeEvaluation` reads
+ * it from context, so every gated code path carries the requirement up to the
+ * command boundary that owns the operator's decision. A command is
+ * gate-blockable precisely when its execution requests this service, which is
+ * what the conformance specification reads instead of a hand-copied list.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+export class ReleaseAgePosture extends ServiceMap.Service()("axm.sh/extension-resolution/ReleaseAgePosture") {
+}
+//# sourceMappingURL=release-age-posture.js.map

package/dist/src/resolution-timeout.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The bound on how long resolving one configured entry's source may take
+ * before the operation reports a network failure instead of waiting.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { ExtensionResolutionFailed } from "./errors.js";
+export declare const CONFIGURED_ENTRY_RESOLUTION_TIMEOUT = "2 seconds";
+export declare const withConfiguredEntryResolutionTimeout: (_source: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, ExtensionResolutionFailed | E, R>;
+//# sourceMappingURL=resolution-timeout.d.ts.map

package/dist/src/resolution-timeout.js

@@ -0,0 +1,17 @@
+/**
+ * The bound on how long resolving one configured entry's source may take
+ * before the operation reports a network failure instead of waiting.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { ExtensionResolutionFailed } from "./errors.js";
+export const CONFIGURED_ENTRY_RESOLUTION_TIMEOUT = "2 seconds";
+export const withConfiguredEntryResolutionTimeout = (_source) => (effect) => effect.pipe(Effect.timeoutOrElse({
+    duration: CONFIGURED_ENTRY_RESOLUTION_TIMEOUT,
+    orElse: () => Effect.fail(new ExtensionResolutionFailed({
+        category: "network",
+        detail: "Timed out while resolving a configured extension source",
+    })),
+}));
+//# sourceMappingURL=resolution-timeout.js.map

package/dist/src/resolved-pack-dependency.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The resolved pack dependency map: the exact identity and version resolution
+ * chose for every declared pack member, in the shape the lockfile records.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+export declare const ResolvedPackDependencySchema: Schema.Union<readonly [Schema.Struct<{
+    readonly source: Schema.Literal<"registry">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly publisherBindingId: Schema.NonEmptyString;
+    readonly integrity: Schema.String;
+}>, Schema.Struct<{
+    readonly source: Schema.Literal<"workspace">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly sourceIdentity: Schema.String;
+    readonly contentIdentity: Schema.brand<Schema.String, "SourceHash">;
+}>]>;
+export type ResolvedPackDependency = typeof ResolvedPackDependencySchema.Type;
+export declare const ResolvedPackDependencyMapSchema: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
+    readonly source: Schema.Literal<"registry">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly publisherBindingId: Schema.NonEmptyString;
+    readonly integrity: Schema.String;
+}>, Schema.Struct<{
+    readonly source: Schema.Literal<"workspace">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly sourceIdentity: Schema.String;
+    readonly contentIdentity: Schema.brand<Schema.String, "SourceHash">;
+}>]>>;
+export type ResolvedPackDependencyMap = typeof ResolvedPackDependencyMapSchema.Type;
+//# sourceMappingURL=resolved-pack-dependency.d.ts.map

package/dist/src/resolved-pack-dependency.js

@@ -0,0 +1,28 @@
+/**
+ * The resolved pack dependency map: the exact identity and version resolution
+ * chose for every declared pack member, in the shape the lockfile records.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+import { ExtensionFqnSchema } from "@agentxm/extension-model/unstable/extensions";
+import { SourceHashSchema } from "@agentxm/extension-model/unstable/sources/source-hash";
+import { VersionSchema } from "@agentxm/extension-model/unstable/version-constraints";
+const ResolvedRegistryDependencySchema = Schema.Struct({
+    source: Schema.Literal("registry"),
+    version: VersionSchema,
+    publisherBindingId: Schema.NonEmptyString,
+    integrity: Schema.String,
+});
+const ResolvedWorkspaceDependencySchema = Schema.Struct({
+    source: Schema.Literal("workspace"),
+    version: VersionSchema,
+    sourceIdentity: Schema.String,
+    contentIdentity: SourceHashSchema,
+});
+export const ResolvedPackDependencySchema = Schema.Union([
+    ResolvedRegistryDependencySchema,
+    ResolvedWorkspaceDependencySchema,
+]);
+export const ResolvedPackDependencyMapSchema = Schema.Record(ExtensionFqnSchema, ResolvedPackDependencySchema);
+//# sourceMappingURL=resolved-pack-dependency.js.map

package/dist/src/source-authority.d.ts

@@ -0,0 +1,60 @@
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+export type SourceAuthorityRelationship = {
+    readonly kind: "root";
+} | {
+    readonly kind: "member";
+    readonly root: string;
+};
+export type WorkspaceAuthorityStatus = "usable" | "missing" | "constraint-mismatch" | "wrong-origin" | "corrupt" | "incomplete" | "locally-modified" | "not-applicable";
+export interface SourceAuthorityTarget {
+    readonly type: ExtensionType;
+    readonly name: string;
+    readonly identity: string;
+}
+export interface SourceAuthorityInput {
+    readonly target: SourceAuthorityTarget;
+    readonly relationship: SourceAuthorityRelationship;
+    readonly requested: {
+        readonly identity: string;
+        readonly workspace: boolean;
+    };
+    readonly configured?: {
+        readonly identity: string;
+        readonly workspace: boolean;
+        readonly version?: string;
+        readonly status?: WorkspaceAuthorityStatus;
+    };
+    readonly requiredVersionRange?: string;
+    readonly allowWorkspaceReplacement?: boolean;
+}
+export type SourceAuthorityBlockedCause = "workspace-source-replacement" | "workspace-identity-mismatch" | "workspace-version-incompatible" | "workspace-unusable";
+export interface SourceAuthorityBlockedFact {
+    readonly id: string;
+    readonly target: SourceAuthorityTarget;
+    readonly relationship: SourceAuthorityRelationship;
+    readonly requestedSource: string;
+    readonly configuredSource: string;
+    readonly cause: SourceAuthorityBlockedCause;
+    readonly detail: string;
+    readonly workspaceVersion?: string;
+    readonly requiredVersionRange?: string;
+    readonly recovery: ReadonlyArray<{
+        readonly description: string;
+    }>;
+}
+export type SourceAuthorityDecision = {
+    readonly kind: "allow-requested";
+} | {
+    readonly kind: "workspace-satisfied";
+    readonly target: SourceAuthorityTarget;
+    readonly relationship: Extract<SourceAuthorityRelationship, {
+        readonly kind: "member";
+    }>;
+    readonly configuredSource: string;
+    readonly workspaceVersion?: string;
+} | {
+    readonly kind: "blocked";
+    readonly fact: SourceAuthorityBlockedFact;
+};
+export declare const evaluateSourceAuthority: (input: SourceAuthorityInput) => SourceAuthorityDecision;
+//# sourceMappingURL=source-authority.d.ts.map

package/dist/src/source-authority.js

@@ -0,0 +1,70 @@
+import * as semver from "semver";
+const blocked = (input, configured, cause, detail, recovery) => ({
+    kind: "blocked",
+    fact: {
+        id: `workspace-authority:${input.relationship.kind}:${input.target.identity}:${cause}`,
+        target: input.target,
+        relationship: input.relationship,
+        requestedSource: input.requested.identity,
+        configuredSource: configured.identity,
+        cause,
+        detail,
+        ...(configured.version === undefined ? {} : { workspaceVersion: configured.version }),
+        ...(input.requiredVersionRange === undefined
+            ? {}
+            : { requiredVersionRange: input.requiredVersionRange }),
+        recovery,
+    },
+});
+export const evaluateSourceAuthority = (input) => {
+    const configured = input.configured;
+    if (configured === undefined ||
+        !configured.workspace ||
+        input.requested.workspace ||
+        input.allowWorkspaceReplacement === true) {
+        return { kind: "allow-requested" };
+    }
+    if (input.relationship.kind === "root") {
+        return blocked(input, configured, "workspace-source-replacement", `Cannot install over workspace-sourced ${input.target.type} "${input.target.name}" with ${input.requested.identity}`, [
+            {
+                description: "Preserve the workspace source, or explicitly transition its authority before installing a different source.",
+            },
+        ]);
+    }
+    const configuredIdentity = configured.identity.startsWith("workspace:")
+        ? configured.identity.slice("workspace:".length)
+        : configured.identity;
+    if (configuredIdentity !== input.target.identity) {
+        return blocked(input, configured, "workspace-identity-mismatch", `Workspace dependency ${configuredIdentity} does not match required ${input.target.identity}`, [
+            {
+                description: "Rename or remove the conflicting workspace dependency, or explicitly transition its authority.",
+            },
+        ]);
+    }
+    if (configured.status !== undefined &&
+        configured.status !== "usable" &&
+        configured.status !== "constraint-mismatch") {
+        return blocked(input, configured, "workspace-unusable", `Workspace dependency ${input.target.identity} is ${configured.status}`, [
+            {
+                description: `Repair or explicitly remove the ${configured.status} workspace dependency before installing the pack.`,
+            },
+        ]);
+    }
+    if (input.requiredVersionRange !== undefined &&
+        (configured.version === undefined ||
+            !semver.satisfies(configured.version, input.requiredVersionRange))) {
+        return blocked(input, configured, "workspace-version-incompatible", `Workspace dependency ${input.target.identity}@${configured.version ?? "unknown"} does not satisfy ${input.requiredVersionRange}`, [
+            {
+                description: `Update the workspace dependency to satisfy ${input.requiredVersionRange}, or explicitly transition its authority.`,
+            },
+        ]);
+    }
+    return {
+        kind: "workspace-satisfied",
+        target: input.target,
+        relationship: input.relationship,
+        configuredSource: configured.identity,
+        ...(configured.version === undefined ? {} : { workspaceVersion: configured.version }),
+    };
+};
+//# sourceMappingURL=source-authority.js.map

package/dist/src/testing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @agentxm/extension-resolution deterministic test ports and decoders.
+ *
+ * The two services a resolution keeps in `R` until its command boundary — the
+ * minimum-release-age posture the operator decides, and the official AXM
+ * skill compatibility policy — bound to fixed values, plus the branded-value
+ * decoders a fixture needs to state a handle, name, version, or range.
+ * Production source never imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Layer from "effect/Layer";
+import { type ExtensionName } from "@agentxm/extension-model/unstable/extensions/common";
+import { type Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { type Version, type VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
+import { AxmSkillCompatibilityPolicy } from "./axm-skill-compatibility.js";
+import { ReleaseAgePosture, type ReleaseAgePostureValue } from "./release-age-posture.js";
+/**
+ * The release-age gate's posture for one run. `"enforce"` withholds a
+ * candidate that has not reached the configured minimum release age, which is
+ * the product's default; pass `"ignore"` to model the operator taking it for
+ * this run only.
+ */
+export declare const ReleaseAgePostureTest: (posture?: ReleaseAgePostureValue) => Layer.Layer<ReleaseAgePosture>;
+/**
+ * The real official-skill compatibility policy, evaluated against a stated CLI
+ * version rather than the running executable's. `null` models an executable
+ * that reports no version, which the policy must still answer for.
+ */
+export declare const AxmSkillCompatibilityPolicyTest: (cliVersion: string | null) => Layer.Layer<AxmSkillCompatibilityPolicy>;
+/** The handle a fixture names, decoded into its branded form. */
+export declare const handle: (value: string) => Handle;
+/** The extension name a fixture names, decoded into its branded form. */
+export declare const extensionName: (value: string) => ExtensionName;
+/** One exact version, decoded into its branded form. */
+export declare const exactVersion: (value: string) => Version;
+/** One version range, decoded into its branded form. */
+export declare const versionRange: (value: string) => VersionRange;
+//# sourceMappingURL=testing.d.ts.map

package/dist/src/testing.js

@@ -0,0 +1,40 @@
+/**
+ * @agentxm/extension-resolution deterministic test ports and decoders.
+ *
+ * The two services a resolution keeps in `R` until its command boundary — the
+ * minimum-release-age posture the operator decides, and the official AXM
+ * skill compatibility policy — bound to fixed values, plus the branded-value
+ * decoders a fixture needs to state a handle, name, version, or range.
+ * Production source never imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Layer from "effect/Layer";
+import { decodeExtensionNameSync, } from "@agentxm/extension-model/unstable/extensions/common";
+import { decodeHandleSync } from "@agentxm/extension-model/unstable/extensions/handle";
+import { decodeVersionRangeSync, decodeVersionSync, } from "@agentxm/extension-model/unstable/version-constraints";
+import { AxmSkillCompatibilityPolicy, makeAxmSkillCompatibilityPolicyLayer, } from "./axm-skill-compatibility.js";
+import { ReleaseAgePosture } from "./release-age-posture.js";
+/**
+ * The release-age gate's posture for one run. `"enforce"` withholds a
+ * candidate that has not reached the configured minimum release age, which is
+ * the product's default; pass `"ignore"` to model the operator taking it for
+ * this run only.
+ */
+export const ReleaseAgePostureTest = (posture = "enforce") => Layer.succeed(ReleaseAgePosture, posture);
+/**
+ * The real official-skill compatibility policy, evaluated against a stated CLI
+ * version rather than the running executable's. `null` models an executable
+ * that reports no version, which the policy must still answer for.
+ */
+export const AxmSkillCompatibilityPolicyTest = (cliVersion) => makeAxmSkillCompatibilityPolicyLayer(cliVersion);
+/** The handle a fixture names, decoded into its branded form. */
+export const handle = (value) => decodeHandleSync(value);
+/** The extension name a fixture names, decoded into its branded form. */
+export const extensionName = (value) => decodeExtensionNameSync(value);
+/** One exact version, decoded into its branded form. */
+export const exactVersion = (value) => decodeVersionSync(value);
+/** One version range, decoded into its branded form. */
+export const versionRange = (value) => decodeVersionRangeSync(value);
+//# sourceMappingURL=testing.js.map

package/dist/src/update/constraint-precedence.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Which constraint governs an update when several declare one.
+ *
+ * A workspace can name a version range directly, and every Pack that owns the
+ * extension names one too. The rule is precedence, not intersection: an
+ * explicit workspace constraint is the intent a person expressed and it wins
+ * outright; a wildcard or absent workspace constraint defers to the Packs and
+ * intersects theirs. Where the newest published release is outside whichever
+ * constraint governs, the resolution says so — a held-back version is a fact
+ * a person is owed, not a silent omission.
+ *
+ * Pure over the visible version list; who supplies that list is the caller's.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Option from "effect/Option";
+/**
+ * A pack's constraint on a skill version.
+ */
+export interface PackConstraint {
+    readonly packName: string;
+    readonly constraint: string;
+}
+/**
+ * Collected constraints for a single skill.
+ */
+export interface UpdateConstraints {
+    /** User's version constraint from settings source string. None = no constraint (treat as "*"). */
+    readonly userConstraint: Option.Option<string>;
+    /** Pack constraints from installed pack manifests. */
+    readonly packConstraints: ReadonlyArray<PackConstraint>;
+}
+/**
+ * Result of constraint resolution for a skill.
+ */
+export interface ConstraintResolutionResult {
+    /** The resolved version string. */
+    readonly resolvedVersion: string;
+    /** Warnings generated during resolution. */
+    readonly warnings: ReadonlyArray<string>;
+}
+/**
+ * Resolve the best version for a skill given its constraints and available versions.
+ *
+ * Algorithm:
+ * 1. If user has explicit constraint (not "*"):
+ *    - Find first version (newest-first) satisfying user constraint
+ *    - If none found → return Option.none() (caller should fail)
+ * 2. If user has "*" or no constraint:
+ *    - Collect all pack constraints
+ *    - For each candidate (newest first): check all pack constraints
+ *    - First satisfying all → use it
+ *    - If none satisfies all → use newest, warn about each unsatisfied constraint
+ *
+ * @param versions - Available versions, newest first
+ * @param constraints - Collected constraints for the skill
+ * @param skillName - Skill name for warning messages
+ * @returns Option.some with result if resolved, Option.none if user constraint unsatisfiable
+ */
+export declare const resolveConstrainedVersion: (versions: ReadonlyArray<string>, constraints: UpdateConstraints, skillName: string) => Option.Option<ConstraintResolutionResult>;
+/**
+ * Detect when a pack constraint holds back a user-installed "*" skill.
+ *
+ * Emits a warning when:
+ * - User has skill with no constraint (wants latest)
+ * - Pack constraint resolves to a version below the latest available
+ *
+ * @param latestVersion - The latest available version
+ * @param resolvedVersion - The version that was resolved after constraint application
+ * @param constraints - The skill's constraints
+ * @param skillName - Skill name for warning messages
+ * @returns Warning messages (empty if no holdback detected)
+ */
+export declare const detectHoldbackWarnings: (latestVersion: string, resolvedVersion: string, constraints: UpdateConstraints, skillName: string) => ReadonlyArray<string>;
+//# sourceMappingURL=constraint-precedence.d.ts.map

package/dist/src/update/constraint-precedence.js

@@ -0,0 +1,99 @@
+/**
+ * Which constraint governs an update when several declare one.
+ *
+ * A workspace can name a version range directly, and every Pack that owns the
+ * extension names one too. The rule is precedence, not intersection: an
+ * explicit workspace constraint is the intent a person expressed and it wins
+ * outright; a wildcard or absent workspace constraint defers to the Packs and
+ * intersects theirs. Where the newest published release is outside whichever
+ * constraint governs, the resolution says so — a held-back version is a fact
+ * a person is owed, not a silent omission.
+ *
+ * Pure over the visible version list; who supplies that list is the caller's.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Option from "effect/Option";
+import { decodeVersionSync, decodeVersionRangeSync, versionSatisfiesRange, } from "@agentxm/extension-model/unstable/version-constraints";
+// -----------------------------------------------------------------------------
+// Constraint Resolution
+// -----------------------------------------------------------------------------
+/**
+ * Resolve the best version for a skill given its constraints and available versions.
+ *
+ * Algorithm:
+ * 1. If user has explicit constraint (not "*"):
+ *    - Find first version (newest-first) satisfying user constraint
+ *    - If none found → return Option.none() (caller should fail)
+ * 2. If user has "*" or no constraint:
+ *    - Collect all pack constraints
+ *    - For each candidate (newest first): check all pack constraints
+ *    - First satisfying all → use it
+ *    - If none satisfies all → use newest, warn about each unsatisfied constraint
+ *
+ * @param versions - Available versions, newest first
+ * @param constraints - Collected constraints for the skill
+ * @param skillName - Skill name for warning messages
+ * @returns Option.some with result if resolved, Option.none if user constraint unsatisfiable
+ */
+export const resolveConstrainedVersion = (versions, constraints, skillName) => {
+    const [newest] = versions;
+    if (newest === undefined)
+        return Option.none();
+    const userConstraintStr = Option.getOrElse(constraints.userConstraint, () => "*");
+    const isWildcard = userConstraintStr === "*";
+    // Case 1: User has explicit constraint
+    if (!isWildcard) {
+        const userConstraint = decodeVersionRangeSync(userConstraintStr);
+        const matched = versions.find((v) => versionSatisfiesRange(decodeVersionSync(v), userConstraint));
+        if (matched === undefined)
+            return Option.none();
+        return Option.some({ resolvedVersion: matched, warnings: [] });
+    }
+    // Case 2: User has wildcard — apply pack constraints
+    if (constraints.packConstraints.length === 0) {
+        // No pack constraints — use newest
+        return Option.some({ resolvedVersion: newest, warnings: [] });
+    }
+    // Try each version (newest first) against all pack constraints
+    for (const version of versions) {
+        const allSatisfied = constraints.packConstraints.every((pc) => versionSatisfiesRange(decodeVersionSync(version), decodeVersionRangeSync(pc.constraint)));
+        if (allSatisfied) {
+            return Option.some({ resolvedVersion: version, warnings: [] });
+        }
+    }
+    // No version satisfies all pack constraints — use newest, warn
+    const warnings = constraints.packConstraints
+        .filter((pc) => !versionSatisfiesRange(decodeVersionSync(newest), decodeVersionRangeSync(pc.constraint)))
+        .map((pc) => `${skillName} held at ${newest} by pack "${pc.packName}" (${pc.constraint})`);
+    return Option.some({ resolvedVersion: newest, warnings });
+};
+/**
+ * Detect when a pack constraint holds back a user-installed "*" skill.
+ *
+ * Emits a warning when:
+ * - User has skill with no constraint (wants latest)
+ * - Pack constraint resolves to a version below the latest available
+ *
+ * @param latestVersion - The latest available version
+ * @param resolvedVersion - The version that was resolved after constraint application
+ * @param constraints - The skill's constraints
+ * @param skillName - Skill name for warning messages
+ * @returns Warning messages (empty if no holdback detected)
+ */
+export const detectHoldbackWarnings = (latestVersion, resolvedVersion, constraints, skillName) => {
+    const userConstraintStr = Option.getOrElse(constraints.userConstraint, () => "*");
+    // Only warn for wildcard users (wanting latest)
+    if (userConstraintStr !== "*")
+        return [];
+    // No holdback if resolved to latest
+    if (resolvedVersion === latestVersion)
+        return [];
+    // No pack constraints means no holdback
+    if (constraints.packConstraints.length === 0)
+        return [];
+    return constraints.packConstraints
+        .filter((pc) => !versionSatisfiesRange(decodeVersionSync(latestVersion), decodeVersionRangeSync(pc.constraint)))
+        .map((pc) => `${skillName} held at ${resolvedVersion} by pack "${pc.packName}" (${pc.constraint}), latest is ${latestVersion}`);
+};
+//# sourceMappingURL=constraint-precedence.js.map