@agentxm/registry-protocol 0.28.4-bootstrap.0

package/dist/src/unstable/registry/publication-set.js

@@ -0,0 +1,507 @@
+import { createHash } from "node:crypto";
+import * as Schema from "effect/Schema";
+import * as semver from "semver";
+import { SuggestedActionSchema } from "../suggested-action.js";
+import { ExtensionNameSchema, ExtensionTypeSchema, ExtensionVisibilitySchema, } from "@agentxm/extension-model/unstable/extensions/common";
+import { formatFqn } from "@agentxm/extension-model/unstable/extensions/fqn";
+import { HandleSchema } from "@agentxm/extension-model/unstable/extensions/handle";
+import { VisibilityEvaluationSchema, VisibilityEvaluationUnavailableSchema, VisibilityIntentSchema, } from "../publish/visibility.js";
+import { VersionRangeSchema, VersionSchema, } from "@agentxm/extension-model/unstable/version-constraints";
+import { DeprecationViewSchema, } from "@agentxm/extension-model/unstable/extensions/deprecation";
+export const PUBLICATION_SET_CONTRACT = "publication-set-v2";
+export const MAX_PUBLICATION_SET_CANDIDATES = 100;
+export const Sha256HexSchema = Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)).annotate({
+    identifier: "Sha256Hex",
+});
+const PublicationTargetSchema = Schema.Struct({
+    owner: HandleSchema,
+    type: ExtensionTypeSchema,
+    name: ExtensionNameSchema,
+    version: VersionSchema,
+}).annotate({ identifier: "PublicationTarget" });
+const PackDependencyDescriptorSchema = Schema.Struct({
+    owner: HandleSchema,
+    type: Schema.Literals(["hook", "knowledge", "mcp-server", "rule", "skill", "subagent"]),
+    name: ExtensionNameSchema,
+    range: VersionRangeSchema,
+}).annotate({ identifier: "PackDependencyDescriptor" });
+export const PublicationVisibilityInputSchema = Schema.Struct({
+    intent: Schema.NullOr(VisibilityIntentSchema),
+    request: Schema.NullOr(ExtensionVisibilitySchema),
+}).annotate({ identifier: "PublicationVisibilityInput" });
+const PublicationDescriptorSchema = Schema.Struct({
+    target: PublicationTargetSchema,
+    participation: Schema.Literals(["publish", "verified-existing"]),
+    archiveSha256Hex: Schema.optional(Sha256HexSchema),
+    visibility: PublicationVisibilityInputSchema,
+    pack: Schema.optional(Schema.Struct({
+        dependencies: Schema.Array(PackDependencyDescriptorSchema),
+    })),
+}).annotate({ identifier: "PublicationDescriptor" });
+export const PreviewPublicationSetRequestSchema = Schema.Struct({
+    contract: Schema.Literal(PUBLICATION_SET_CONTRACT),
+    candidates: Schema.Array(PublicationDescriptorSchema),
+}).annotate({ identifier: "PreviewPublicationSetRequest" });
+export const PackDependencyFindingSchema = Schema.Struct({
+    kind: Schema.Literal("advisory"),
+    ruleId: Schema.Literals([
+        "pack/dependency-version-resolvable",
+        "pack/dependency-deprecated",
+    ]),
+    severity: Schema.Literals(["error", "warning"]),
+    reason: Schema.Literals([
+        "selected-new-private",
+        "selected-existing-private",
+        "target-unavailable",
+        "lifecycle-unavailable",
+        "no-installable-version",
+        "range-unsatisfied",
+        "deprecated",
+    ]),
+    dependency: PackDependencyDescriptorSchema,
+    effectiveVisibility: Schema.optional(Schema.Literals(["public", "private"])),
+    lifecycle: Schema.optional(Schema.Literals(["active", "unavailable"])),
+    deprecation: Schema.optional(DeprecationViewSchema),
+    location: Schema.Struct({ file: Schema.Literal("pack.json") }),
+    path: Schema.Literal("./pack.json"),
+    message: Schema.String,
+    suggestions: Schema.Array(SuggestedActionSchema),
+}).annotate({ identifier: "PackDependencyFinding" });
+const ResolvedPublicationCandidateSchema = Schema.Struct({
+    kind: Schema.Literal("resolved"),
+    target: PublicationTargetSchema,
+    participation: Schema.Literals(["publish", "verified-existing"]),
+    descriptorDigest: Sha256HexSchema,
+    visibility: VisibilityEvaluationSchema,
+    condition: Schema.optional(Schema.String),
+});
+const UnavailablePublicationCandidateSchema = Schema.Struct({
+    kind: Schema.Literal("unavailable"),
+    target: PublicationTargetSchema,
+    participation: Schema.Literals(["publish", "verified-existing"]),
+    descriptorDigest: Sha256HexSchema,
+    code: Schema.Literal("publish/target-unavailable"),
+    visibility: VisibilityEvaluationUnavailableSchema,
+});
+const PublicationPackResultSchema = Schema.Struct({
+    target: PublicationTargetSchema,
+    status: Schema.Literals(["admitted", "blocked"]),
+    findings: Schema.Array(PackDependencyFindingSchema),
+    resolutions: Schema.Array(Schema.Struct({
+        dependency: PackDependencyDescriptorSchema,
+        effectiveVersion: VersionSchema,
+    }).annotate({ identifier: "PackDependencyResolution" })),
+});
+export const PreviewPublicationSetResponseSchema = Schema.Struct({
+    contract: Schema.Literal(PUBLICATION_SET_CONTRACT),
+    publicationSetDigest: Sha256HexSchema,
+    status: Schema.Literals(["admitted", "blocked"]),
+    candidates: Schema.Array(Schema.Union([ResolvedPublicationCandidateSchema, UnavailablePublicationCandidateSchema])),
+    packs: Schema.Array(PublicationPackResultSchema),
+}).annotate({ identifier: "PreviewPublicationSetResponse" });
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+export const comparePublicationTargets = (left, right) => compareText(left.owner, right.owner) ||
+    compareText(left.type, right.type) ||
+    compareText(left.name, right.name) ||
+    compareText(left.version, right.version);
+const compareDependencies = (left, right) => compareText(left.owner, right.owner) ||
+    compareText(left.type, right.type) ||
+    compareText(left.name, right.name) ||
+    compareText(left.range, right.range);
+export const normalizePublicationDescriptor = (descriptor) => ({
+    target: descriptor.target,
+    participation: descriptor.participation,
+    visibility: descriptor.visibility,
+    ...(descriptor.archiveSha256Hex === undefined
+        ? {}
+        : { archiveSha256Hex: descriptor.archiveSha256Hex }),
+    ...(descriptor.pack === undefined
+        ? {}
+        : {
+            pack: {
+                dependencies: [...descriptor.pack.dependencies].sort(compareDependencies),
+            },
+        }),
+});
+export const normalizePublicationSet = (descriptors) => descriptors
+    .map(normalizePublicationDescriptor)
+    .sort((left, right) => comparePublicationTargets(left.target, right.target));
+const canonicalBytes = (value) => new TextEncoder().encode(JSON.stringify(value));
+const sha256Hex = (bytes) => Schema.decodeUnknownSync(Sha256HexSchema)(createHash("sha256").update(bytes).digest("hex"));
+export const publicationDescriptorDigest = (descriptor) => sha256Hex(canonicalBytes({
+    contract: PUBLICATION_SET_CONTRACT,
+    descriptor: normalizePublicationDescriptor(descriptor),
+}));
+export const publicationSetDigest = (descriptors) => sha256Hex(canonicalBytes({
+    contract: PUBLICATION_SET_CONTRACT,
+    candidates: normalizePublicationSet(descriptors),
+}));
+export const archiveSha256Hex = (archive) => sha256Hex(archive);
+export const publicationTargetKey = (target) => JSON.stringify([target.owner, target.type, target.name, target.version]);
+const publicationIdentityKey = (target) => `${target.owner}\u0000${target.type}\u0000${target.name}`;
+export const validatePublicationDescriptors = (descriptors) => {
+    if (descriptors.length > MAX_PUBLICATION_SET_CANDIDATES) {
+        throw new RangeError(`Publication sets accept at most ${MAX_PUBLICATION_SET_CANDIDATES} candidates.`);
+    }
+    Schema.decodeUnknownSync(PreviewPublicationSetRequestSchema)({
+        contract: PUBLICATION_SET_CONTRACT,
+        candidates: descriptors,
+    });
+    const identities = new Set();
+    for (const descriptor of descriptors) {
+        const key = publicationIdentityKey(descriptor.target);
+        if (identities.has(key)) {
+            throw new TypeError(`Duplicate publication target ${key}.`);
+        }
+        identities.add(key);
+        if ((descriptor.participation === "publish") !== (descriptor.archiveSha256Hex !== undefined)) {
+            throw new TypeError("archiveSha256Hex is required exactly for publish candidates.");
+        }
+        if ((descriptor.target.type === "pack") !== (descriptor.pack !== undefined)) {
+            throw new TypeError("Pack declarations are required exactly for pack candidates.");
+        }
+    }
+    return normalizePublicationSet(descriptors);
+};
+const findingBase = (finding) => ({
+    kind: "advisory",
+    location: { file: "pack.json" },
+    path: "./pack.json",
+    ...finding,
+});
+const dependencyError = (input) => {
+    const fqn = formatFqn(input.snapshot.dependency);
+    return findingBase({
+        ruleId: "pack/dependency-version-resolvable",
+        severity: "error",
+        reason: input.reason,
+        dependency: input.snapshot.dependency,
+        ...(input.discloseState !== true
+            ? {}
+            : {
+                ...(input.snapshot.visibility === "public" || input.snapshot.visibility === "private"
+                    ? { effectiveVisibility: input.snapshot.visibility }
+                    : {}),
+                ...(input.snapshot.lifecycleState === null
+                    ? {}
+                    : { lifecycle: input.snapshot.lifecycleState === "active" ? "active" : "unavailable" }),
+            }),
+        message: `Dependency ${fqn} requests range "${input.snapshot.dependency.range}", but ${input.explanation}.`,
+        suggestions: input.suggestions,
+    });
+};
+const evaluateDependencySnapshot = (snapshot, packVisibility) => {
+    const fqn = formatFqn(snapshot.dependency);
+    if (!snapshot.exists) {
+        return [
+            dependencyError({
+                snapshot,
+                reason: "target-unavailable",
+                explanation: "that extension does not exist in the registry",
+                suggestions: [
+                    {
+                        description: `Publish ${fqn} or correct the dependency identity`,
+                        cmd: `axm publish ${fqn}`,
+                    },
+                ],
+            }),
+        ];
+    }
+    if (packVisibility === "public" && snapshot.visibility !== "public") {
+        return [
+            dependencyError({
+                snapshot,
+                reason: "target-unavailable",
+                explanation: "that extension is not public",
+                suggestions: [{ description: `Make ${fqn} public or depend on a public extension` }],
+            }),
+        ];
+    }
+    if (snapshot.lifecycleState !== "active") {
+        return [
+            dependencyError({
+                snapshot,
+                reason: "lifecycle-unavailable",
+                explanation: "that extension is not active",
+                discloseState: true,
+                suggestions: [{ description: `Restore ${fqn} to active state or remove it from the pack` }],
+            }),
+        ];
+    }
+    const installable = snapshot.versions.filter((version) => version.status === "available" && !version.yanked && !version.purged);
+    if (installable.length === 0) {
+        return [
+            dependencyError({
+                snapshot,
+                reason: "no-installable-version",
+                explanation: "it has no installable versions",
+                discloseState: true,
+                suggestions: [
+                    {
+                        description: `Publish an installable version of ${fqn} or remove it from the pack`,
+                        cmd: `axm publish ${fqn}`,
+                    },
+                ],
+            }),
+        ];
+    }
+    if (!installable.some((candidate) => semver.satisfies(candidate.version, snapshot.dependency.range))) {
+        return [
+            dependencyError({
+                snapshot,
+                reason: "range-unsatisfied",
+                explanation: "no installable version satisfies the requested range",
+                discloseState: true,
+                suggestions: [
+                    {
+                        description: `Publish a version of ${fqn} satisfying "${snapshot.dependency.range}" or correct the requested range`,
+                        cmd: `axm publish ${fqn}`,
+                    },
+                ],
+            }),
+        ];
+    }
+    return snapshot.deprecation !== null
+        ? [
+            findingBase({
+                ruleId: "pack/dependency-deprecated",
+                severity: "warning",
+                reason: "deprecated",
+                dependency: snapshot.dependency,
+                effectiveVisibility: snapshot.visibility === "private" ? "private" : "public",
+                lifecycle: "active",
+                deprecation: snapshot.deprecation,
+                message: `Dependency ${fqn} requests range "${snapshot.dependency.range}" and resolves to a deprecated extension.`,
+                suggestions: [
+                    { description: `Prefer a supported replacement for ${fqn} when one is available` },
+                ],
+            }),
+        ]
+        : [];
+};
+const dependencyIdentityKey = (dependency) => `${dependency.owner}\u0000${dependency.type}\u0000${dependency.name}`;
+export const evaluateProspectivePackDependencies = (input) => {
+    const snapshots = new Map(input.snapshots.map((snapshot) => [dependencyIdentityKey(snapshot.dependency), snapshot]));
+    const candidates = new Map(input.candidates.map((candidate) => [
+        publicationIdentityKey(candidate.descriptor.target),
+        candidate,
+    ]));
+    return input.dependencies
+        .flatMap((dependency) => {
+        const current = snapshots.get(dependencyIdentityKey(dependency)) ??
+            {
+                dependency,
+                exists: false,
+                visibility: null,
+                lifecycleState: null,
+                deprecation: null,
+                versions: [],
+            };
+        const selected = candidates.get(dependencyIdentityKey(dependency));
+        if (selected === undefined)
+            return evaluateDependencySnapshot(current, input.packVisibility);
+        if (selected.kind === "unavailable") {
+            return [
+                dependencyError({
+                    snapshot: current,
+                    reason: "target-unavailable",
+                    explanation: "that selected target is unavailable",
+                    suggestions: [
+                        {
+                            description: `Verify authority and availability for ${formatFqn(dependency)}, then preview the complete set again`,
+                        },
+                    ],
+                }),
+            ];
+        }
+        if (input.packVisibility === "public" && selected.visibility.resolved?.value === "private") {
+            return [
+                dependencyError({
+                    snapshot: { ...current, exists: true, visibility: "private" },
+                    reason: current.exists ? "selected-existing-private" : "selected-new-private",
+                    explanation: "the selected dependency will remain private",
+                    discloseState: true,
+                    suggestions: current.exists
+                        ? [
+                            {
+                                description: `Make ${formatFqn(dependency)} public explicitly, then preview the complete set again`,
+                            },
+                        ]
+                        : [
+                            {
+                                description: `Publish ${formatFqn(dependency)} as public, then preview the complete set again`,
+                                cmd: `axm publish ${formatFqn(dependency)} --visibility public`,
+                            },
+                        ],
+                }),
+            ];
+        }
+        return evaluateDependencySnapshot({
+            ...current,
+            exists: true,
+            visibility: selected.visibility.resolved?.value ?? current.visibility,
+            lifecycleState: current.exists ? current.lifecycleState : "active",
+            versions: selected.descriptor.participation === "publish"
+                ? [
+                    ...current.versions,
+                    {
+                        version: selected.descriptor.target.version,
+                        status: "available",
+                        yanked: false,
+                        purged: false,
+                    },
+                ]
+                : current.versions,
+        }, input.packVisibility);
+    })
+        .sort((left, right) => compareText(formatFqn(left.dependency), formatFqn(right.dependency)) ||
+        compareText(left.dependency.range, right.dependency.range));
+};
+/**
+ * Evaluate dependency admission and expose the exact version an ordinary
+ * Registry consumer would resolve from the same prospective snapshot.
+ */
+export const evaluateProspectivePackDependencyState = (input) => {
+    const findings = evaluateProspectivePackDependencies(input);
+    const snapshots = new Map(input.snapshots.map((snapshot) => [dependencyIdentityKey(snapshot.dependency), snapshot]));
+    const candidates = new Map(input.candidates.map((candidate) => [
+        publicationIdentityKey(candidate.descriptor.target),
+        candidate,
+    ]));
+    const resolutions = input.dependencies.flatMap((dependency) => {
+        const current = snapshots.get(dependencyIdentityKey(dependency)) ??
+            {
+                dependency,
+                exists: false,
+                visibility: null,
+                lifecycleState: null,
+                deprecation: null,
+                versions: [],
+            };
+        const selected = candidates.get(dependencyIdentityKey(dependency));
+        if (selected?.kind === "unavailable" ||
+            (input.packVisibility === "public" && selected?.visibility.resolved?.value === "private")) {
+            return [];
+        }
+        const prospective = selected === undefined
+            ? current
+            : {
+                ...current,
+                exists: true,
+                visibility: selected.visibility.resolved?.value ?? current.visibility,
+                lifecycleState: current.exists ? current.lifecycleState : "active",
+                versions: selected.descriptor.participation === "publish"
+                    ? [
+                        ...current.versions,
+                        {
+                            version: selected.descriptor.target.version,
+                            status: "available",
+                            yanked: false,
+                            purged: false,
+                        },
+                    ]
+                    : current.versions,
+            };
+        if (!prospective.exists ||
+            (input.packVisibility === "public" && prospective.visibility !== "public") ||
+            prospective.lifecycleState !== "active") {
+            return [];
+        }
+        const effectiveVersion = semver.maxSatisfying(prospective.versions
+            .filter((version) => version.status === "available" && !version.yanked && !version.purged)
+            .map((version) => version.version), dependency.range);
+        return effectiveVersion === null
+            ? []
+            : [
+                {
+                    dependency,
+                    effectiveVersion: Schema.decodeUnknownSync(VersionSchema)(effectiveVersion),
+                },
+            ];
+    });
+    return {
+        findings,
+        resolutions: [...resolutions].sort((left, right) => compareDependencies(left.dependency, right.dependency)),
+    };
+};
+export const validatePublicationSetResponse = (descriptors, response) => {
+    const normalized = validatePublicationDescriptors(descriptors);
+    const expectedDigest = publicationSetDigest(normalized);
+    if (response.publicationSetDigest !== expectedDigest) {
+        throw new TypeError("The publication-set digest does not match the submitted descriptors.");
+    }
+    const expectedCandidates = new Map(normalized.map((descriptor) => [publicationTargetKey(descriptor.target), descriptor]));
+    if (response.candidates.length !== expectedCandidates.size) {
+        throw new TypeError("The publication-set response does not account for every candidate.");
+    }
+    for (const candidate of response.candidates) {
+        const key = publicationTargetKey(candidate.target);
+        const descriptor = expectedCandidates.get(key);
+        if (descriptor === undefined ||
+            candidate.participation !== descriptor.participation ||
+            candidate.descriptorDigest !== publicationDescriptorDigest(descriptor)) {
+            throw new TypeError("The publication-set response contains an incompatible candidate.");
+        }
+        const expectedFqn = formatFqn(candidate.target);
+        if (candidate.visibility.target !== expectedFqn) {
+            throw new TypeError("The publication-set response evaluates the wrong visibility target.");
+        }
+        if (candidate.kind === "resolved") {
+            if (candidate.visibility.resolved === null ||
+                JSON.stringify(candidate.visibility.intent) !==
+                    JSON.stringify(descriptor.visibility.intent) ||
+                candidate.visibility.request !== descriptor.visibility.request) {
+                throw new TypeError("The publication-set response changed submitted visibility authority.");
+            }
+        }
+        if ((response.status === "admitted" &&
+            candidate.kind === "resolved" &&
+            candidate.participation === "publish") !==
+            (candidate.kind === "resolved" && candidate.condition !== undefined)) {
+            throw new TypeError("Publication conditions are valid only for admitted upload candidates.");
+        }
+    }
+    const visibilityBlocked = response.candidates.some((candidate) => candidate.kind === "unavailable" ||
+        candidate.visibility.findings.some((finding) => finding.severity === "error"));
+    const packBlocked = response.packs.some((pack) => pack.status === "blocked");
+    if ((response.status === "blocked") !== (visibilityBlocked || packBlocked)) {
+        throw new TypeError("The publication-set status does not match its candidate findings.");
+    }
+    const expectedPacks = normalized.filter((descriptor) => descriptor.target.type === "pack" && descriptor.participation === "publish");
+    if (response.packs.length !== expectedPacks.length) {
+        throw new TypeError("The publication-set response does not account for every publishable pack.");
+    }
+    const packKeys = new Set();
+    for (const pack of response.packs) {
+        const key = publicationTargetKey(pack.target);
+        const descriptor = expectedPacks.find((candidate) => publicationTargetKey(candidate.target) === key);
+        if (packKeys.has(key) || descriptor === undefined) {
+            throw new TypeError("The publication-set response contains an incompatible pack result.");
+        }
+        packKeys.add(key);
+        if (pack.status === "blocked") {
+            if (pack.resolutions.length > 0) {
+                throw new TypeError("Blocked pack results cannot claim effective dependency resolutions.");
+            }
+            continue;
+        }
+        const expectedDependencies = descriptor.pack?.dependencies ?? [];
+        if (pack.resolutions.length !== expectedDependencies.length) {
+            throw new TypeError("An admitted pack result does not account for every effective dependency resolution.");
+        }
+        const resolutionKeys = new Set();
+        for (const resolution of pack.resolutions) {
+            const dependencyKey = dependencyIdentityKey(resolution.dependency);
+            const expected = expectedDependencies.find((dependency) => dependencyIdentityKey(dependency) === dependencyKey);
+            if (resolutionKeys.has(dependencyKey) ||
+                expected === undefined ||
+                expected.range !== resolution.dependency.range ||
+                !semver.satisfies(resolution.effectiveVersion, resolution.dependency.range)) {
+                throw new TypeError("The publication-set response contains an incompatible effective dependency resolution.");
+            }
+            resolutionKeys.add(dependencyKey);
+        }
+    }
+    return response;
+};
+//# sourceMappingURL=publication-set.js.map

package/dist/src/unstable/registry/release-age-policy.d.ts

@@ -0,0 +1,57 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { ExtensionFqnParts } from "@agentxm/extension-model/unstable/extensions/common";
+import type { ReleaseAgeEvaluation, ReleaseAgeEvidence, ReleaseAgeExemption } from "@agentxm/extension-model/unstable/extensions/release-age";
+import type { VersionEntry } from "./schema.js";
+export declare const releaseAgeExemptionForIdentity: (evaluation: ReleaseAgeEvaluation, identity: ExtensionFqnParts) => ReleaseAgeExemption | undefined;
+export interface ReleaseAgeRecordBase {
+    readonly reason: "minimum-release-age";
+    readonly target: string;
+    readonly dependencyPath: ReadonlyArray<string>;
+    readonly requestedRange?: string;
+    readonly currentVersion?: string;
+    readonly selectedVersion?: string;
+    readonly candidateVersion: string;
+    readonly publishedAt: string;
+    readonly eligibleAt: string;
+    readonly minimumReleaseAgeSeconds: number;
+}
+export type ReleaseAgeHoldbackRecord = ReleaseAgeRecordBase;
+export type ReleaseAgeBypassRecord = ReleaseAgeRecordBase & ({
+    readonly bypassCause: "exclude";
+    readonly exemptionScope: "project" | "user";
+} | {
+    readonly bypassCause: "ignore-flag";
+});
+export type ReleaseAgeRecord = ReleaseAgeHoldbackRecord | ReleaseAgeBypassRecord;
+export interface ReleaseAgeOperationEvidence {
+    readonly evaluatedAt: string;
+    readonly holdbacks: ReadonlyArray<ReleaseAgeHoldbackRecord>;
+    readonly bypasses: ReadonlyArray<ReleaseAgeBypassRecord>;
+}
+/** Deduplicate and order operation evidence independently from concurrent resolution order. */
+export declare const normalizeReleaseAgeRecords: <Record extends ReleaseAgeRecord>(records: ReadonlyArray<Record>) => ReadonlyArray<Record>;
+export declare const DEFAULT_MINIMUM_RELEASE_AGE = "24h";
+export declare const DEFAULT_MINIMUM_RELEASE_AGE_DURATION: Duration.Duration;
+export declare const parseMinimumReleaseAge: (value: string) => Option.Option<Duration.Duration>;
+/**
+ * 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 declare const formatMinimumReleaseAgeSeconds: (seconds: number) => string;
+export declare const isVersionEntryMature: (entry: VersionEntry, minimumAge: Duration.Duration) => Effect.Effect<boolean>;
+export declare const isVersionEntryEligibleAt: (entry: VersionEntry, evaluation: ReleaseAgeEvaluation) => boolean;
+export declare const releaseAgeEvidence: (entry: VersionEntry, evaluation: ReleaseAgeEvaluation) => ReleaseAgeEvidence;
+export declare const filterMatureVersions: (versions: ReadonlyArray<VersionEntry>, minimumAge: Duration.Duration) => Effect.Effect<ReadonlyArray<VersionEntry>>;
+export declare const releaseAgeHoldbackWarning: (args: {
+    readonly fqn: string;
+    readonly selectedVersion: string;
+    readonly heldVersion: string;
+    readonly minimumReleaseAge: string;
+}) => string;
+//# sourceMappingURL=release-age-policy.d.ts.map

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

@@ -0,0 +1,117 @@
+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);
+};
+export const DEFAULT_MINIMUM_RELEASE_AGE = "24h";
+export const DEFAULT_MINIMUM_RELEASE_AGE_DURATION = Duration.hours(24);
+/**
+ * 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