@agentxm/workspace-projection 0.28.14-preview.1789139351.5cd4595aa

package/dist/src/constraint-invariant-fact.js

@@ -0,0 +1,156 @@
+/**
+ * Shared invariant facts for desired extension version constraints.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as semver from "semver";
+import { parseExtensionFqnParts, } from "@agentxm/extension-model/unstable/extensions";
+export const EXTENSION_CONSTRAINT_INVARIANT_PREDICATE = "workspace/extension-constraints-satisfied";
+const constraintContributorOrder = (left, right) => (left.dependingPack ?? "").localeCompare(right.dependingPack ?? "") ||
+    left.range.localeCompare(right.range) ||
+    left.location.localeCompare(right.location);
+/**
+ * Evaluate prospective selected versions against the locally represented Pack
+ * constraints. Selected Pack manifests replace their current local declaration
+ * for this fact evaluation, matching the state that a coordinated publication
+ * would establish.
+ */
+export const makeProspectiveExtensionConstraintFacts = (args) => {
+    const selectedPacks = new Map(args.candidates
+        .filter((candidate) => candidate.type === "pack")
+        .map((candidate) => [candidate.fqn, candidate]));
+    const recordsByMember = new Map();
+    for (const record of args.reachability) {
+        const current = recordsByMember.get(record.memberFqn);
+        if (current === undefined)
+            recordsByMember.set(record.memberFqn, [record]);
+        else
+            current.push(record);
+    }
+    return args.candidates
+        .filter((candidate) => candidate.type !== "pack")
+        .flatMap((candidate) => {
+        const parsed = parseExtensionFqnParts(candidate.fqn);
+        if (parsed === undefined || parsed.type !== candidate.type)
+            return [];
+        const constraints = (recordsByMember.get(candidate.fqn) ?? [])
+            .flatMap((record) => {
+            const selectedPack = selectedPacks.get(record.packFqn);
+            const range = selectedPack === undefined
+                ? record.constraint
+                : selectedPack.dependencies?.[candidate.fqn];
+            if (range === undefined)
+                return [];
+            return [
+                {
+                    source: "pack",
+                    dependingPack: record.packFqn,
+                    range,
+                    location: record.manifestPath,
+                    authority: selectedPack === undefined ? record.packAuthority : "workspace",
+                },
+            ];
+        })
+            .sort(constraintContributorOrder);
+        const violations = constraints.filter((constraint) => !semver.satisfies(candidate.version, constraint.range));
+        if (violations.length === 0)
+            return [];
+        return [
+            {
+                predicate: EXTENSION_CONSTRAINT_INVARIANT_PREDICATE,
+                subject: {
+                    type: parsed.type,
+                    name: parsed.name,
+                    identity: candidate.fqn,
+                },
+                authority: {
+                    source: "prospective-publish-selection",
+                    locator: `${candidate.fqn}@${candidate.version}`,
+                    constraints,
+                },
+                observation: {
+                    status: "constraint-mismatch",
+                    candidateVersion: candidate.version,
+                    violations,
+                },
+                expectation: {
+                    status: "satisfied",
+                    ranges: constraints
+                        .map(({ range }) => range)
+                        .sort((left, right) => left.localeCompare(right)),
+                },
+            },
+        ];
+    })
+        .sort((left, right) => left.subject.identity.localeCompare(right.subject.identity));
+};
+export const makeExtensionConstraintInvariantFact = (desired, observation) => ({
+    predicate: EXTENSION_CONSTRAINT_INVARIANT_PREDICATE,
+    subject: {
+        type: desired.type,
+        name: desired.name,
+        identity: desired.identity.replace(/^workspace:/, ""),
+        ...(observation.path === undefined ? {} : { path: observation.path }),
+    },
+    authority: {
+        source: observation.authority.source,
+        locator: observation.authority.locator,
+        constraints: observation.authority.constraints,
+    },
+    observation: {
+        status: observation.status,
+        ...(observation.acceptedVersion === undefined
+            ? {}
+            : { acceptedVersion: observation.acceptedVersion }),
+        ...(observation.observedVersion === undefined
+            ? {}
+            : { observedVersion: observation.observedVersion }),
+    },
+    expectation: {
+        status: "satisfied",
+        ranges: [...desired.constraints].sort((left, right) => left.localeCompare(right)),
+    },
+});
+export const planExtensionConstraintFact = (fact, candidateVersion) => {
+    if (candidateVersion === undefined) {
+        return { readiness: "blocked", reason: "no-satisfying-version" };
+    }
+    if (fact.expectation.ranges.every((constraint) => semver.satisfies(candidateVersion, constraint))) {
+        return {
+            readiness: "ready",
+            reason: "satisfying-version-resolved",
+            version: candidateVersion,
+        };
+    }
+    return {
+        readiness: "blocked",
+        reason: "candidate-violates-constraints",
+        candidateVersion,
+    };
+};
+const contributorText = (contributor) => contributor.source === "pack"
+    ? `${contributor.dependingPack ?? "unknown Pack"} range=${contributor.range} location=${contributor.location}`
+    : `settings range=${contributor.range} location=${contributor.location}`;
+/** Stable human and machine-display detail shared by lint and sync. */
+export const extensionConstraintFactText = (fact) => {
+    const constraints = fact.authority.constraints.map(contributorText).join(", ");
+    const versions = [
+        fact.observation.acceptedVersion === undefined
+            ? undefined
+            : `accepted version=${fact.observation.acceptedVersion}`,
+        fact.observation.observedVersion === undefined
+            ? undefined
+            : `observed version=${fact.observation.observedVersion}`,
+        fact.observation.candidateVersion === undefined
+            ? undefined
+            : `candidate version=${fact.observation.candidateVersion}`,
+    ].filter((part) => part !== undefined);
+    return [
+        `fact=${fact.predicate}`,
+        `${fact.subject.type} '${fact.subject.identity}' has constraint mismatch`,
+        `authority=${fact.authority.source}:${fact.authority.locator}`,
+        `constraints=${constraints.length === 0 ? fact.expectation.ranges.join(", ") : constraints}`,
+        ...versions,
+    ].join("; ");
+};
+//# sourceMappingURL=constraint-invariant-fact.js.map

package/dist/src/contributors.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared contributor-set resolution for aggregate ownership units.
+ *
+ * An aggregate managed output (the Rules region, an agent's managed hook
+ * entries, the Hook fallback region, the Knowledge discovery region) is always
+ * rendered whole from the complete contributor set the desired-state graph
+ * reaches. Writers receive contributors from these helpers and never derive
+ * membership from raw settings entries, lock rows, or the unit's own content.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import type * as Path from "effect/Path";
+import { AuthoredContributorUnsupported, ContributorIdentityInvalid, ContributorTreeMismatch, ContributorUnresolved, DesiredStateIncomplete } from "./errors.js";
+import { type ExtensionType, type ExtensionTypePlural } from "@agentxm/extension-model/unstable/extensions";
+import { type ExtensionPathLockEntry } from "@agentxm/workspace-state";
+import { type MaterializedTreeInvalid, type TreeIntegrity } from "@agentxm/workspace-state";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import type { DesiredExtensionNode, DesiredStateGraph } from "@agentxm/workspace-state";
+import type { WorkspaceLayout } from "@agentxm/workspace-state";
+/**
+ * Minimal structural view of a per-extension source lock entry. Registry
+ * entries locate a canonical package under the registry extensions tree;
+ * every other source class materializes under the external extensions tree.
+ */
+export type SourceLockEntryLike = ExtensionPathLockEntry & {
+    readonly workspaceName: string;
+    readonly packageOwner?: Handle | undefined;
+    readonly treeIntegrity: TreeIntegrity;
+};
+/** One member of an aggregate unit's contributor set, resolved to content. */
+export interface AggregateContributor {
+    readonly node: DesiredExtensionNode;
+    readonly packageRoot: string;
+    /**
+     * Marker identity owner for registry and workspace sources. Git and local
+     * sources derive marker identity from the canonical manifest instead.
+     */
+    readonly identityOwner: Option.Option<Handle>;
+}
+/** Stable recovery-conformance identity for aggregate writes blocked by an incomplete graph. */
+export declare const INCOMPLETE_DESIRED_STATE_BLOCKER_ID: "projection/desired-state-graph-complete";
+/**
+ * Gate aggregate-unit writes on a complete desired-state graph. An operation
+ * that cannot enumerate the complete contributor set writes nothing.
+ */
+export declare const requireCompleteGraph: (graph: DesiredStateGraph) => Effect.Effect<DesiredStateGraph, DesiredStateIncomplete>;
+/** Enabled desired nodes of one extension type. */
+export declare const activeNodesOfType: (graph: DesiredStateGraph, type: ExtensionType) => ReadonlyArray<DesiredExtensionNode>;
+/**
+ * Resolve the canonical package root for one contributor from its node
+ * identity and accepted lock entry. Never reads settings, never resolves
+ * sources, and never touches the network.
+ */
+export declare const contributorForNode: (args: {
+    readonly layout: WorkspaceLayout;
+    readonly path: Path.Path;
+    readonly node: DesiredExtensionNode;
+    /** Type-specific segment under the extensions trees, e.g. `rules`. */
+    readonly extensionDir: ExtensionTypePlural;
+    readonly locked: SourceLockEntryLike | undefined;
+}) => Effect.Effect<AggregateContributor, AuthoredContributorUnsupported | ContributorIdentityInvalid | ContributorUnresolved | ContributorTreeMismatch | MaterializedTreeInvalid, FileSystem.FileSystem | Path.Path>;
+/**
+ * Resolve the complete contributor set for one extension type: every enabled
+ * node the complete desired-state graph reaches, whether declared directly or
+ * contributed by a Pack, each resolved to its canonical package root.
+ */
+export declare const activeContributors: (args: {
+    readonly layout: WorkspaceLayout;
+    readonly path: Path.Path;
+    readonly type: ExtensionType;
+    readonly extensionDir: ExtensionTypePlural;
+    readonly graph: DesiredStateGraph;
+    readonly locked: Readonly<Record<string, SourceLockEntryLike>>;
+}) => Effect.Effect<ReadonlyArray<AggregateContributor>, DesiredStateIncomplete | AuthoredContributorUnsupported | ContributorIdentityInvalid | ContributorUnresolved | ContributorTreeMismatch | MaterializedTreeInvalid, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=contributors.d.ts.map

package/dist/src/contributors.js

@@ -0,0 +1,82 @@
+/**
+ * Shared contributor-set resolution for aggregate ownership units.
+ *
+ * An aggregate managed output (the Rules region, an agent's managed hook
+ * entries, the Hook fallback region, the Knowledge discovery region) is always
+ * rendered whole from the complete contributor set the desired-state graph
+ * reaches. Writers receive contributors from these helpers and never derive
+ * membership from raw settings entries, lock rows, or the unit's own content.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { AuthoredContributorUnsupported, ContributorIdentityInvalid, ContributorTreeMismatch, ContributorUnresolved, DesiredStateIncomplete, } from "./errors.js";
+import { parseExtensionFqnParts, } from "@agentxm/extension-model/unstable/extensions";
+import { computeExtensionPathsForLayout, extensionPathSourceFromLockEntry, } from "@agentxm/workspace-state";
+import { computeMaterializedTreeIntegrity, } from "@agentxm/workspace-state";
+import { desiredStateProblemsText } from "@agentxm/workspace-state";
+/** Stable recovery-conformance identity for aggregate writes blocked by an incomplete graph. */
+export const INCOMPLETE_DESIRED_STATE_BLOCKER_ID = "projection/desired-state-graph-complete";
+/**
+ * Gate aggregate-unit writes on a complete desired-state graph. An operation
+ * that cannot enumerate the complete contributor set writes nothing.
+ */
+export const requireCompleteGraph = (graph) => graph.complete
+    ? Effect.succeed(graph)
+    : new DesiredStateIncomplete({ problems: desiredStateProblemsText(graph.problems) });
+/** Enabled desired nodes of one extension type. */
+export const activeNodesOfType = (graph, type) => graph.nodes.filter((node) => node.type === type && node.enabled);
+/**
+ * Resolve the canonical package root for one contributor from its node
+ * identity and accepted lock entry. Never reads settings, never resolves
+ * sources, and never touches the network.
+ */
+export const contributorForNode = (args) => Effect.gen(function* () {
+    const { extensionDir, layout, locked, node, path } = args;
+    if (node.identity.startsWith("workspace:")) {
+        if (layout.scope === "user") {
+            return yield* new AuthoredContributorUnsupported({ type: node.type });
+        }
+        const identity = parseExtensionFqnParts(node.identity.slice("workspace:".length));
+        if (identity === undefined || identity.type !== node.type) {
+            return yield* new ContributorIdentityInvalid({
+                type: node.type,
+                identity: node.identity,
+            });
+        }
+        return {
+            node,
+            packageRoot: path.join(layout.authoredRoot(node.type), identity.name),
+            identityOwner: Option.some(identity.owner),
+        };
+    }
+    if (locked === undefined) {
+        return yield* new ContributorUnresolved({ type: node.type, name: node.name });
+    }
+    const packageRoot = computeExtensionPathsForLayout(path.join, layout, extensionPathSourceFromLockEntry(locked), extensionDir, locked.workspaceName).canonicalPath;
+    const observedTree = yield* computeMaterializedTreeIntegrity(packageRoot);
+    if (observedTree !== locked.treeIntegrity) {
+        return yield* new ContributorTreeMismatch({ packageRoot });
+    }
+    return {
+        node,
+        packageRoot,
+        identityOwner: locked.type === "registry"
+            ? Option.some(locked.owner)
+            : Option.fromUndefinedOr(locked.packageOwner),
+    };
+});
+/**
+ * Resolve the complete contributor set for one extension type: every enabled
+ * node the complete desired-state graph reaches, whether declared directly or
+ * contributed by a Pack, each resolved to its canonical package root.
+ */
+export const activeContributors = (args) => requireCompleteGraph(args.graph).pipe(Effect.flatMap((graph) => Effect.forEach(activeNodesOfType(graph, args.type), (node) => contributorForNode({
+    layout: args.layout,
+    path: args.path,
+    node,
+    extensionDir: args.extensionDir,
+    locked: args.locked[node.name],
+}))));
+//# sourceMappingURL=contributors.js.map

package/dist/src/errors.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Typed failure family for shared projection: aggregate contributor
+ * resolution and managed-region reconciliation. Fields are domain facts; the
+ * application error boundary owns rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+declare const DesiredStateIncomplete_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DesiredStateIncomplete";
+} & Readonly<A>;
+/** Aggregate writes are gated on a completely enumerable desired-state graph. */
+export declare class DesiredStateIncomplete extends DesiredStateIncomplete_base<{
+    /** Rendered pack and declaration problem text. */
+    readonly problems: string;
+}> {
+}
+declare const AuthoredContributorUnsupported_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "AuthoredContributorUnsupported";
+} & Readonly<A>;
+/** User workspaces cannot contribute workspace-authored packages. */
+export declare class AuthoredContributorUnsupported extends AuthoredContributorUnsupported_base<{
+    readonly type: string;
+}> {
+}
+declare const ContributorIdentityInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ContributorIdentityInvalid";
+} & Readonly<A>;
+/** A workspace-authored contributor's identity did not parse to its type. */
+export declare class ContributorIdentityInvalid extends ContributorIdentityInvalid_base<{
+    readonly type: string;
+    readonly identity: string;
+}> {
+}
+declare const ContributorUnresolved_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ContributorUnresolved";
+} & Readonly<A>;
+/** An active contributor has no accepted lock resolution. */
+export declare class ContributorUnresolved extends ContributorUnresolved_base<{
+    readonly type: string;
+    readonly name: string;
+}> {
+}
+declare const ContributorTreeMismatch_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ContributorTreeMismatch";
+} & Readonly<A>;
+/** The materialized package tree does not match the accepted lock entry. */
+export declare class ContributorTreeMismatch extends ContributorTreeMismatch_base<{
+    readonly packageRoot: string;
+}> {
+}
+declare const ProjectionTargetUnsupported_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ProjectionTargetUnsupported";
+} & Readonly<A>;
+/** The managed-region target file type does not support comment markers. */
+export declare class ProjectionTargetUnsupported extends ProjectionTargetUnsupported_base<{
+    /** The complete refusal sentence; call sites own type-specific wording. */
+    readonly detail: string;
+}> {
+}
+declare const ManagedRegionViolation_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ManagedRegionViolation";
+} & Readonly<A>;
+/** A managed region exists but cannot be reconciled without guessing. */
+export declare class ManagedRegionViolation extends ManagedRegionViolation_base<{
+    readonly displayPath: string;
+    /** The inspection's message for malformed or unsupported-version regions. */
+    readonly reason?: string;
+    /**
+     * The inspection's structured reason. Callers classify ownership validity
+     * from this field; they never re-read the sentence in `reason`.
+     */
+    readonly reasonCode?: "managed-region-malformed" | "managed-region-unsupported-version";
+}> {
+}
+declare const ProjectionIoFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ProjectionIoFailed";
+} & Readonly<A>;
+/** A managed-region filesystem step failed. */
+export declare class ProjectionIoFailed extends ProjectionIoFailed_base<{
+    readonly path: string;
+    readonly step: "inspect" | "read" | "reconcile";
+    readonly cause: unknown;
+}> {
+}
+declare const ProjectionParticipantFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ProjectionParticipantFailed";
+} & Readonly<A>;
+/**
+ * A projection participant could not produce or observe its plans, and the
+ * failure belongs to the producing capability rather than to projection. The
+ * participant states the fact in its own words; projection never renders it
+ * and never receives an application error envelope.
+ */
+export declare class ProjectionParticipantFailed extends ProjectionParticipantFailed_base<{
+    /** The unit the participant was asked for. */
+    readonly unitId: string;
+    /** The producing capability's own sentence for the failure. */
+    readonly detail: string;
+}> {
+}
+/** Every failure the shared projection module constructs. */
+export type ProjectionError = DesiredStateIncomplete | AuthoredContributorUnsupported | ContributorIdentityInvalid | ContributorUnresolved | ContributorTreeMismatch | ProjectionTargetUnsupported | ManagedRegionViolation | ProjectionIoFailed;
+/**
+ * Whether a failure belongs to projection's own family. Owners use this to
+ * pass projection failures through with their exact identity instead of
+ * restating them.
+ */
+export declare const isProjectionError: <E extends {
+    readonly _tag: string;
+}>(failure: E) => failure is E & ProjectionError;
+/**
+ * Every failure a projection participant may report to the fact evaluator:
+ * projection's own family, plus the participant's stated failure.
+ */
+export type ProjectionParticipantFailure = ProjectionError | ProjectionParticipantFailed;
+/** Reconciliation failures a managed text-region write may produce. */
+export type ManagedRegionFailure = ManagedRegionViolation | ProjectionTargetUnsupported | ProjectionIoFailed;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.js

@@ -0,0 +1,57 @@
+/**
+ * Typed failure family for shared projection: aggregate contributor
+ * resolution and managed-region reconciliation. Fields are domain facts; the
+ * application error boundary owns rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+/** Aggregate writes are gated on a completely enumerable desired-state graph. */
+export class DesiredStateIncomplete extends Data.TaggedError("DesiredStateIncomplete") {
+}
+/** User workspaces cannot contribute workspace-authored packages. */
+export class AuthoredContributorUnsupported extends Data.TaggedError("AuthoredContributorUnsupported") {
+}
+/** A workspace-authored contributor's identity did not parse to its type. */
+export class ContributorIdentityInvalid extends Data.TaggedError("ContributorIdentityInvalid") {
+}
+/** An active contributor has no accepted lock resolution. */
+export class ContributorUnresolved extends Data.TaggedError("ContributorUnresolved") {
+}
+/** The materialized package tree does not match the accepted lock entry. */
+export class ContributorTreeMismatch extends Data.TaggedError("ContributorTreeMismatch") {
+}
+/** The managed-region target file type does not support comment markers. */
+export class ProjectionTargetUnsupported extends Data.TaggedError("ProjectionTargetUnsupported") {
+}
+/** A managed region exists but cannot be reconciled without guessing. */
+export class ManagedRegionViolation extends Data.TaggedError("ManagedRegionViolation") {
+}
+/** A managed-region filesystem step failed. */
+export class ProjectionIoFailed extends Data.TaggedError("ProjectionIoFailed") {
+}
+/**
+ * A projection participant could not produce or observe its plans, and the
+ * failure belongs to the producing capability rather than to projection. The
+ * participant states the fact in its own words; projection never renders it
+ * and never receives an application error envelope.
+ */
+export class ProjectionParticipantFailed extends Data.TaggedError("ProjectionParticipantFailed") {
+}
+const PROJECTION_ERROR_TAGS = new Set([
+    "DesiredStateIncomplete",
+    "AuthoredContributorUnsupported",
+    "ContributorIdentityInvalid",
+    "ContributorUnresolved",
+    "ContributorTreeMismatch",
+    "ProjectionTargetUnsupported",
+    "ManagedRegionViolation",
+    "ProjectionIoFailed",
+]);
+/**
+ * Whether a failure belongs to projection's own family. Owners use this to
+ * pass projection failures through with their exact identity instead of
+ * restating them.
+ */
+export const isProjectionError = (failure) => PROJECTION_ERROR_TAGS.has(failure._tag);
+//# sourceMappingURL=errors.js.map

package/dist/src/exclusions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Contributors a projection unit could not render, and the report an operator
+ * reads because of it.
+ *
+ * A desired contributor whose package cannot be inspected cannot supply a row
+ * in the unit it belongs to, so the truthful rendering omits it. Omission is
+ * never silent: every site that renders or observes the unit reports the
+ * exclusion, and keeps reporting it until the package is fixed or removed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+/** Why a desired contributor could not be rendered. */
+export type ProjectionExclusionReason = "package-missing" | "package-invalid";
+/** One desired contributor left out of its ownership unit. */
+export interface ProjectionContributorExclusion {
+    /** Extension name as the operator declared it. */
+    readonly contributor: string;
+    readonly reason: ProjectionExclusionReason;
+    /**
+     * The inspector's diagnostic sentence for an invalid package. Terminal
+     * reports carry this sentence; the underlying error chain stays in
+     * structured output.
+     */
+    readonly detail?: string;
+}
+/**
+ * The operator-facing report: consequence, bundle, reason, remedy. It never
+ * names the projection machinery and never carries the raw error chain.
+ */
+export declare const formatProjectionExclusion: (args: {
+    readonly exclusion: ProjectionContributorExclusion;
+    readonly targetFile: string;
+}) => string;
+/** Format every exclusion recorded against one target file, in input order. */
+export declare const formatProjectionExclusions: (args: {
+    readonly exclusions: ReadonlyArray<ProjectionContributorExclusion>;
+    readonly targetFile: string;
+}) => ReadonlyArray<string>;
+//# sourceMappingURL=exclusions.d.ts.map

package/dist/src/exclusions.js

@@ -0,0 +1,34 @@
+/**
+ * Contributors a projection unit could not render, and the report an operator
+ * reads because of it.
+ *
+ * A desired contributor whose package cannot be inspected cannot supply a row
+ * in the unit it belongs to, so the truthful rendering omits it. Omission is
+ * never silent: every site that renders or observes the unit reports the
+ * exclusion, and keeps reporting it until the package is fixed or removed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+const fileLabel = (targetFile) => {
+    const segments = targetFile.split(/[\\/]/);
+    return segments[segments.length - 1] ?? targetFile;
+};
+const asSentenceBody = (detail) => detail.trim().replace(/\.+$/, "");
+/**
+ * The operator-facing report: consequence, bundle, reason, remedy. It never
+ * names the projection machinery and never carries the raw error chain.
+ */
+export const formatProjectionExclusion = (args) => {
+    const { contributor, reason, detail } = args.exclusion;
+    const file = fileLabel(args.targetFile);
+    if (reason === "package-missing") {
+        return `${contributor} was left out of ${file} because its package is missing. Remove it with \`axm knowledge uninstall ${contributor}\`, or restore its files and run \`axm sync\`.`;
+    }
+    const because = detail === undefined
+        ? "because its package is invalid"
+        : `because its package is invalid: ${asSentenceBody(detail)}`;
+    return `${contributor} was left out of ${file} ${because}. Fix the file and run \`axm sync\`.`;
+};
+/** Format every exclusion recorded against one target file, in input order. */
+export const formatProjectionExclusions = (args) => args.exclusions.map((exclusion) => formatProjectionExclusion({ exclusion, targetFile: args.targetFile }));
+//# sourceMappingURL=exclusions.js.map

package/dist/src/expected-names.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The names an agent-facing projection is expected to hold.
+ *
+ * Lint, sync, and agent removal all reconcile native output against the same
+ * expectation: every enabled desired extension of each per-agent type, with
+ * subagents also expected in the Skill container because that is where their
+ * profile is projected. Deriving it once keeps the three callers from drifting
+ * apart.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { PerAgentType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { DesiredStateGraph } from "@agentxm/workspace-state";
+/** Expected native entry names per per-agent extension type. */
+export type ExpectedProjectionNames = Readonly<Record<PerAgentType, ReadonlySet<string>>>;
+/** Assemble the expectation from name sets a caller already holds. */
+export declare const expectedProjectionNamesOf: (names: {
+    readonly skill: ReadonlySet<string>;
+    readonly subagent: ReadonlySet<string>;
+    readonly mcpServer: ReadonlySet<string>;
+    readonly hook: ReadonlySet<string>;
+}) => ExpectedProjectionNames;
+/** Assemble the expectation from the enabled nodes of a desired-state graph. */
+export declare const expectedProjectionNames: (graph: DesiredStateGraph) => ExpectedProjectionNames;
+//# sourceMappingURL=expected-names.d.ts.map

package/dist/src/expected-names.js

@@ -0,0 +1,29 @@
+/**
+ * The names an agent-facing projection is expected to hold.
+ *
+ * Lint, sync, and agent removal all reconcile native output against the same
+ * expectation: every enabled desired extension of each per-agent type, with
+ * subagents also expected in the Skill container because that is where their
+ * profile is projected. Deriving it once keeps the three callers from drifting
+ * apart.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+/** Assemble the expectation from name sets a caller already holds. */
+export const expectedProjectionNamesOf = (names) => ({
+    skill: new Set([...names.skill, ...names.subagent]),
+    subagent: names.subagent,
+    "mcp-server": names.mcpServer,
+    hook: names.hook,
+});
+/** Assemble the expectation from the enabled nodes of a desired-state graph. */
+export const expectedProjectionNames = (graph) => {
+    const enabled = (type) => new Set(graph.nodes.filter((node) => node.enabled && node.type === type).map(({ name }) => name));
+    return expectedProjectionNamesOf({
+        skill: enabled("skill"),
+        subagent: enabled("subagent"),
+        mcpServer: enabled("mcp-server"),
+        hook: enabled("hook"),
+    });
+};
+//# sourceMappingURL=expected-names.js.map

package/dist/src/generation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Compute a stable provenance token from explicitly selected authoritative
+ * inputs. The rendered projection is deliberately not an input.
+ */
+export declare const projectionGeneration: (parts: ReadonlyArray<string>) => string;
+//# sourceMappingURL=generation.d.ts.map

package/dist/src/generation.js

@@ -0,0 +1,7 @@
+import { computeSourceHash } from "@agentxm/workspace-state";
+/**
+ * Compute a stable provenance token from explicitly selected authoritative
+ * inputs. The rendered projection is deliberately not an input.
+ */
+export const projectionGeneration = (parts) => computeSourceHash(JSON.stringify(parts));
+//# sourceMappingURL=generation.js.map

package/dist/src/hooks/outcomes.d.ts

@@ -0,0 +1,14 @@
+import type { Agent } from "@agentxm/extension-model/unstable/agent-capabilities";
+import type { ConfiguredAgentOutcome } from "@agentxm/workspace-state";
+import type { HookManifest } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
+export interface HookOutcomeTarget {
+    readonly nativePath?: string;
+    readonly fallbackPath: string;
+}
+export declare const evaluateHookAgentOutcome: (args: {
+    readonly agent: Agent;
+    readonly manifest: HookManifest;
+    readonly target: HookOutcomeTarget;
+    readonly state: "projected" | "current";
+}) => ConfiguredAgentOutcome;
+//# sourceMappingURL=outcomes.d.ts.map