@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/lockfile/schema.js

@@ -0,0 +1,406 @@
+/**
+ * Lockfile schema definition.
+ *
+ * The lockfile (axm-lock.yaml) records accepted immutable resolutions for
+ * externally sourced extensions.
+ *
+ * Lockfile v6 is authority, not receipt history. It contains no authored,
+ * bundled, inline, projection, completion-time, or command-history state.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+import { HandleSchema } from "@agentxm/extension-model/unstable/extensions";
+import { SourceHashSchema } from "@agentxm/extension-model/unstable/sources/source-hash";
+import { TreeIntegritySchema } from "../workspace/materialized-tree.js";
+import { ExtensionNameSchema } from "@agentxm/extension-model/unstable/extensions/common";
+import { VersionSchema } from "@agentxm/extension-model/unstable/version-constraints";
+import { SourceNamespaceSchema, SourceRefSchema, SourceSegmentSchema, SourceSubPathSchema, } from "@agentxm/extension-model/unstable/sources/types";
+export const LOCKFILE_VERSION = 6;
+// =============================================================================
+// Flat Source Schemas (discriminated by type field)
+// =============================================================================
+const looksAbsolutePath = (value) => value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("\\\\");
+const LocalSourceLockPathSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((value) => looksAbsolutePath(value) ? "Expected a relative local source path" : undefined)));
+// =============================================================================
+// Source Lock Entry Factory
+// =============================================================================
+/**
+ * Creates the external-source lock-entry union.
+ *
+ * Used to produce lock-entry schemas with feature-specific shared fields.
+ */
+const makeSourceLockUnion = (extensionType, packageOwner, packageFormat, extraFields) => Schema.Union([
+    Schema.Struct({
+        type: Schema.Literal("github"),
+        sourceType: Schema.Literal("github"),
+        sourceName: Schema.String,
+        endpoint: Schema.URLFromString,
+        extensionType: Schema.Literal(extensionType),
+        workspaceName: ExtensionNameSchema,
+        packageFormat,
+        packageOwner,
+        packageName: ExtensionNameSchema,
+        owner: SourceNamespaceSchema,
+        repo: SourceSegmentSchema,
+        ref: Schema.optional(SourceRefSchema),
+        path: Schema.optional(SourceSubPathSchema),
+        resolvedCommit: Schema.NonEmptyString,
+        resolvedTree: Schema.NonEmptyString,
+        contentIdentity: SourceHashSchema,
+        treeIntegrity: TreeIntegritySchema,
+        ...extraFields,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("gitlab"),
+        sourceType: Schema.Literal("gitlab"),
+        sourceName: Schema.String,
+        endpoint: Schema.URLFromString,
+        extensionType: Schema.Literal(extensionType),
+        workspaceName: ExtensionNameSchema,
+        packageFormat,
+        packageOwner,
+        packageName: ExtensionNameSchema,
+        owner: SourceNamespaceSchema,
+        repo: SourceSegmentSchema,
+        ref: Schema.optional(SourceRefSchema),
+        path: Schema.optional(SourceSubPathSchema),
+        resolvedCommit: Schema.NonEmptyString,
+        resolvedTree: Schema.NonEmptyString,
+        contentIdentity: SourceHashSchema,
+        treeIntegrity: TreeIntegritySchema,
+        ...extraFields,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("bitbucket"),
+        sourceType: Schema.Literal("bitbucket"),
+        sourceName: Schema.String,
+        endpoint: Schema.URLFromString,
+        extensionType: Schema.Literal(extensionType),
+        workspaceName: ExtensionNameSchema,
+        packageFormat,
+        packageOwner,
+        packageName: ExtensionNameSchema,
+        owner: SourceNamespaceSchema,
+        repo: SourceSegmentSchema,
+        ref: Schema.optional(SourceRefSchema),
+        path: Schema.optional(SourceSubPathSchema),
+        resolvedCommit: Schema.NonEmptyString,
+        resolvedTree: Schema.NonEmptyString,
+        contentIdentity: SourceHashSchema,
+        treeIntegrity: TreeIntegritySchema,
+        ...extraFields,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("azurerepos"),
+        sourceType: Schema.Literal("azurerepos"),
+        sourceName: Schema.String,
+        endpoint: Schema.URLFromString,
+        extensionType: Schema.Literal(extensionType),
+        workspaceName: ExtensionNameSchema,
+        packageFormat,
+        packageOwner,
+        packageName: ExtensionNameSchema,
+        organization: SourceSegmentSchema,
+        project: SourceSegmentSchema,
+        repo: SourceSegmentSchema,
+        ref: Schema.optional(SourceRefSchema),
+        path: Schema.optional(SourceSubPathSchema),
+        resolvedCommit: Schema.NonEmptyString,
+        resolvedTree: Schema.NonEmptyString,
+        contentIdentity: SourceHashSchema,
+        treeIntegrity: TreeIntegritySchema,
+        ...extraFields,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("git"),
+        sourceType: Schema.Literal("git"),
+        sourceName: Schema.Literal("git"),
+        extensionType: Schema.Literal(extensionType),
+        workspaceName: ExtensionNameSchema,
+        packageFormat,
+        packageOwner,
+        packageName: ExtensionNameSchema,
+        url: Schema.String,
+        ref: Schema.optional(SourceRefSchema),
+        path: Schema.optional(SourceSubPathSchema),
+        resolvedCommit: Schema.NonEmptyString,
+        resolvedTree: Schema.NonEmptyString,
+        contentIdentity: SourceHashSchema,
+        treeIntegrity: TreeIntegritySchema,
+        ...extraFields,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("local"),
+        sourceType: Schema.Literal("local"),
+        sourceName: Schema.Literal("local"),
+        extensionType: Schema.Literal(extensionType),
+        workspaceName: ExtensionNameSchema,
+        packageFormat,
+        packageOwner,
+        packageName: ExtensionNameSchema,
+        path: LocalSourceLockPathSchema,
+        contentIdentity: SourceHashSchema,
+        treeIntegrity: TreeIntegritySchema,
+        ...extraFields,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("registry"),
+        sourceType: Schema.Literal("registry"),
+        endpoint: Schema.URLFromString,
+        extensionType: Schema.Literal(extensionType),
+        workspaceName: ExtensionNameSchema,
+        packageFormat: Schema.Literal("agentxm"),
+        owner: HandleSchema,
+        name: ExtensionNameSchema,
+        resolvedVersion: VersionSchema,
+        integrity: Schema.String.annotate({
+            description: "SRI sha512 of the published archive, verified against downloaded bytes before " +
+                "extraction. The supply-chain guarantee for registry installs; never compared " +
+                "against installed files on disk.",
+        }),
+        sourceName: Schema.String,
+        publisherBindingId: Schema.NonEmptyString,
+        treeIntegrity: TreeIntegritySchema,
+        ...extraFields,
+    }),
+]);
+// =============================================================================
+// Skill Lock Entry (union of all source types)
+// =============================================================================
+/**
+ * Lock entry for a single installed skill.
+ * Discriminated union by the `type` field.
+ *
+ * Every external source carries immutable accepted-resolution identity:
+ * registry version/integrity/publisher binding, Git commit/tree/content identity,
+ * or local-path content identity.
+ *
+ * Source-specific fields are at the top level based on source type.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const SkillLockEntrySchema = makeSourceLockUnion("skill", Schema.optional(HandleSchema), Schema.Literals(["agentxm", "agent-skill"]), {});
+// =============================================================================
+// Skills Lock Map
+// =============================================================================
+/**
+ * Map of skill names to their lock entries.
+ * Skill names are simple identifiers (not FQN patterns).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const SkillsLockMapSchema = Schema.Record(Schema.String, SkillLockEntrySchema);
+// =============================================================================
+// Subagent Lock Entry (union of all source types)
+// =============================================================================
+/**
+ * Common fields for subagent lock entries.
+ */
+/**
+ * Lock entry for a single installed subagent.
+ * Discriminated union by the `type` field.
+ *
+ * External source entries carry immutable accepted-resolution identity.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const SubagentLockEntrySchema = makeSourceLockUnion("subagent", HandleSchema, Schema.Literal("agentxm"), {});
+// =============================================================================
+// Subagents Lock Map
+// =============================================================================
+/**
+ * Map of subagent names to their lock entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const SubagentsLockMapSchema = Schema.Record(Schema.String, SubagentLockEntrySchema);
+// =============================================================================
+// MCP Server Lock Entry (union of all source types, no agents)
+// =============================================================================
+/**
+ * Lock entry for a single installed MCP server.
+ * Discriminated union by the `type` field.
+ *
+ * Same structure as SkillLockEntry but without the `agents` field.
+ *
+ * External source entries carry immutable accepted-resolution identity. Inline
+ * servers are authored settings and therefore have no lock row.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const McpServerLockEntrySchema = makeSourceLockUnion("mcp-server", HandleSchema, Schema.Literal("agentxm"), {});
+// =============================================================================
+// MCP Servers Lock Map
+// =============================================================================
+/**
+ * Map of MCP server names to their lock entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const McpServersLockMapSchema = Schema.Record(Schema.String, McpServerLockEntrySchema);
+/**
+ * Materialized file target recorded for rule and hook lifecycle decisions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+// =============================================================================
+// Rule Lock Entry (union of all source types, no agents)
+// =============================================================================
+/**
+ * Lock entry for a single installed rule.
+ *
+ * External source entries carry immutable accepted-resolution identity.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const RuleLockEntrySchema = makeSourceLockUnion("rule", HandleSchema, Schema.Literal("agentxm"), {});
+/**
+ * Map of rule names to their lock entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const RulesLockMapSchema = Schema.Record(Schema.String, RuleLockEntrySchema);
+// =============================================================================
+// Hook Lock Entry (union of all source types, no agents)
+// =============================================================================
+/**
+ * Lock entry for a single installed hook.
+ *
+ * External source entries carry immutable accepted-resolution identity.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const HookLockEntrySchema = makeSourceLockUnion("hook", HandleSchema, Schema.Literal("agentxm"), {});
+/**
+ * Map of hook names to their lock entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const HooksLockMapSchema = Schema.Record(Schema.String, HookLockEntrySchema);
+// =============================================================================
+// Knowledge Lock Entry (isolated OKF bundle plus derived index)
+// =============================================================================
+/**
+ * Lock entry for a single installed knowledge bundle.
+ *
+ * External source entries carry immutable accepted-resolution identity.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const KnowledgeLockEntrySchema = makeSourceLockUnion("knowledge", HandleSchema, Schema.Literal("agentxm"), {});
+export const KnowledgeLockMapSchema = Schema.Record(Schema.String, KnowledgeLockEntrySchema);
+// =============================================================================
+// Pack Lock Entry
+// =============================================================================
+/**
+ * Registry pack lock entry - pack from a registry.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const RegistryPackLockEntrySchema = Schema.Struct({
+    type: Schema.Literal("registry"),
+    sourceType: Schema.Literal("registry"),
+    endpoint: Schema.URLFromString,
+    extensionType: Schema.Literal("pack"),
+    workspaceName: ExtensionNameSchema,
+    packageFormat: Schema.Literal("agentxm"),
+    owner: HandleSchema,
+    name: ExtensionNameSchema,
+    resolvedVersion: VersionSchema,
+    integrity: Schema.String,
+    manifestContentIdentity: SourceHashSchema,
+    sourceName: Schema.String,
+    publisherBindingId: Schema.NonEmptyString,
+    treeIntegrity: TreeIntegritySchema,
+}).annotate({
+    identifier: "RegistryPackLockEntry",
+    title: "Registry Pack Lock Entry",
+    description: "Pinned version info for a pack installed from a registry.",
+});
+/**
+ * Build a registry pack lock entry from typed args.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const makeRegistryPackLockEntry = (args) => ({
+    type: "registry",
+    ...args,
+});
+/**
+ * Lock entry for a single installed pack.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const PackLockEntrySchema = RegistryPackLockEntrySchema.annotate({
+    identifier: "PackLockEntry",
+    title: "Pack Lock Entry",
+    description: "Accepted immutable resolution for a Registry Pack.",
+});
+// =============================================================================
+// Packs Lock Map
+// =============================================================================
+/**
+ * Map of pack names to their lock entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const PacksLockMapSchema = Schema.Record(Schema.String, PackLockEntrySchema);
+// =============================================================================
+// Lock entry schemas by extension type
+// =============================================================================
+/**
+ * Every catalog extension type's lock-entry schema, keyed by type.
+ *
+ * Total by construction: a new extension type fails compile here until its lock
+ * entry exists. The parity conformance suite decodes a synthetic entry through
+ * each schema to check obligations that must hold for every type.
+ *
+ * Packs are excluded — a pack lock entry records resolved members rather than a
+ * single installed source, so it is not shape-comparable with the others.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const LOCK_ENTRY_SCHEMA_BY_TYPE = {
+    skill: SkillLockEntrySchema,
+    "mcp-server": McpServerLockEntrySchema,
+    subagent: SubagentLockEntrySchema,
+    rule: RuleLockEntrySchema,
+    hook: HookLockEntrySchema,
+    knowledge: KnowledgeLockEntrySchema,
+};
+// =============================================================================
+// Lockfile
+// =============================================================================
+/**
+ * Schema for lockfile (axm-lock.yaml).
+ *
+ * The lockfile records the exact resolved state of all installed extensions,
+ * enabling reproducible installations across environments.
+ *
+ * Structure:
+ * - lockfileVersion: Schema version (currently 6)
+ * - skills: Map of skill names to their lock entries
+ * - packs: Map of pack names to their lock entries (optional)
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+const LockfileBaseSchema = Schema.Struct({
+    lockfileVersion: Schema.Literal(LOCKFILE_VERSION).pipe(Schema.annotate({
+        description: "Lockfile schema version.",
+        default: LOCKFILE_VERSION,
+    }), Schema.annotateKey({ messageMissingKey: "lockfileVersion is required" })),
+    skills: SkillsLockMapSchema.pipe(Schema.annotateKey({ messageMissingKey: "skills map is required" })),
+    subagents: Schema.optional(SubagentsLockMapSchema),
+    mcpServers: Schema.optional(McpServersLockMapSchema),
+    rules: Schema.optional(RulesLockMapSchema),
+    hooks: Schema.optional(HooksLockMapSchema),
+    knowledge: Schema.optional(KnowledgeLockMapSchema),
+    packs: Schema.optional(PacksLockMapSchema),
+});
+export const LockfileSchema = LockfileBaseSchema.annotate({
+    identifier: "Lockfile",
+    title: "AXM Lockfile",
+    description: "Accepted immutable external source resolutions and provenance. Desired state and projection ownership are authoritative elsewhere.",
+});
+//# sourceMappingURL=schema.js.map

package/dist/src/schema/index.d.ts

@@ -0,0 +1,3 @@
+export type { JsonFileReadResult } from "./types.js";
+export { readAndValidateJsonFile } from "./read-and-validate-json-file.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/schema/index.js

@@ -0,0 +1,2 @@
+export { readAndValidateJsonFile } from "./read-and-validate-json-file.js";
+//# sourceMappingURL=index.js.map

package/dist/src/schema/read-and-validate-json-file.d.ts

@@ -0,0 +1,20 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+import type { JsonFileReadResult } from "./types.js";
+/**
+ * Read a JSON file, parse it, and validate it against a schema.
+ *
+ * Returns a {@link JsonFileReadResult} discriminated union so callers can
+ * decide how to present each failure mode (missing file, I/O error, malformed
+ * JSON, schema mismatch) without catching exceptions.
+ *
+ * @param filePath - Absolute path to the JSON file.
+ * @param schema   - Effect Schema to validate the parsed JSON against.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const readAndValidateJsonFile: <S extends Schema.Top>(filePath: string, schema: S, options?: {
+    readonly maxSchemaIssues?: number;
+}) => Effect.Effect<JsonFileReadResult<S["Type"]>, never, FileSystem.FileSystem | S["DecodingServices"]>;
+//# sourceMappingURL=read-and-validate-json-file.d.ts.map

package/dist/src/schema/read-and-validate-json-file.js

@@ -0,0 +1,85 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { formatSchemaIssuesToLines } from "@agentxm/extension-model/unstable/schema-issues";
+/**
+ * Extract a human-readable location string from a JSON `SyntaxError`.
+ *
+ * Returns `Option.some("at position N")` or `Option.some("line N column N")`
+ * when the engine includes position information, otherwise `Option.none()`.
+ */
+const extractParseErrorLocation = (error) => {
+    if (error instanceof SyntaxError && typeof error.message === "string") {
+        const posMatch = /at position (\d+)/.exec(error.message);
+        if (posMatch !== null) {
+            return Option.some(`at position ${posMatch[1]}`);
+        }
+        const lineMatch = /line (\d+) column (\d+)/.exec(error.message);
+        if (lineMatch !== null) {
+            return Option.some(`line ${lineMatch[1]} column ${lineMatch[2]}`);
+        }
+    }
+    return Option.none();
+};
+/**
+ * Read a JSON file, parse it, and validate it against a schema.
+ *
+ * Returns a {@link JsonFileReadResult} discriminated union so callers can
+ * decide how to present each failure mode (missing file, I/O error, malformed
+ * JSON, schema mismatch) without catching exceptions.
+ *
+ * @param filePath - Absolute path to the JSON file.
+ * @param schema   - Effect Schema to validate the parsed JSON against.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const readAndValidateJsonFile = (filePath, schema, options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    // 1. Check existence
+    const existsResult = yield* Effect.result(fs.exists(filePath));
+    if (existsResult._tag === "Failure") {
+        return {
+            _tag: "read-failure",
+            error: `Failed to check if file exists: ${String(existsResult.failure)}`,
+        };
+    }
+    if (!existsResult.success) {
+        return { _tag: "missing" };
+    }
+    // 2. Read file
+    const readResult = yield* Effect.result(fs.readFileString(filePath));
+    if (readResult._tag === "Failure") {
+        return {
+            _tag: "read-failure",
+            error: `Failed to read file: ${String(readResult.failure)}`,
+        };
+    }
+    // 3. Parse JSON
+    const parseResult = yield* Effect.result(Effect.try({
+        try: () => JSON.parse(readResult.success),
+        catch: (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            const location = Option.getOrUndefined(extractParseErrorLocation(error));
+            return { message, location };
+        },
+    }));
+    if (parseResult._tag === "Failure") {
+        const failure = parseResult.failure;
+        return {
+            _tag: "unparseable",
+            error: failure.message,
+            ...(failure.location !== undefined ? { location: failure.location } : {}),
+        };
+    }
+    // 4. Validate against schema
+    const decoded = yield* Effect.result(Schema.decodeUnknownEffect(schema)(parseResult.success));
+    if (decoded._tag === "Failure") {
+        return {
+            _tag: "schema-invalid",
+            issues: formatSchemaIssuesToLines(decoded.failure.issue, options?.maxSchemaIssues),
+        };
+    }
+    return { _tag: "ok", value: decoded.success };
+});
+//# sourceMappingURL=read-and-validate-json-file.js.map

package/dist/src/schema/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Discriminated union representing the outcome of reading and validating a JSON
+ * file against a schema.
+ *
+ * The `ok` variant carries the decoded value so callers that need it can avoid
+ * re-reading the file.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type JsonFileReadResult<A> = {
+    readonly _tag: "ok";
+    readonly value: A;
+} | {
+    readonly _tag: "missing";
+} | {
+    readonly _tag: "read-failure";
+    readonly error: string;
+} | {
+    readonly _tag: "unparseable";
+    readonly error: string;
+    readonly location?: string;
+} | {
+    readonly _tag: "schema-invalid";
+    readonly issues: ReadonlyArray<string>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/schema/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/settings/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Typed failure family for settings writes. 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 SettingsWriteError_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: "SettingsWriteError";
+} & Readonly<A>;
+/**
+ * Settings write failure at one step of the write pipeline. `path` carries
+ * the fact each step's message interpolates: the settings directory for
+ * `mkdir`, the temp file for `write-temp`, and the settings path otherwise.
+ */
+export declare class SettingsWriteError extends SettingsWriteError_base<{
+    readonly path: string;
+    readonly step: "mkdir" | "encode" | "write-temp" | "rename";
+    readonly cause: unknown;
+}> {
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/settings/errors.js

@@ -0,0 +1,15 @@
+/**
+ * Typed failure family for settings writes. 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";
+/**
+ * Settings write failure at one step of the write pipeline. `path` carries
+ * the fact each step's message interpolates: the settings directory for
+ * `mkdir`, the temp file for `write-temp`, and the settings path otherwise.
+ */
+export class SettingsWriteError extends Data.TaggedError("SettingsWriteError") {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/settings/format-preserving-json.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Format-preserving JSON modification utilities.
+ *
+ * Detects and preserves existing formatting (indentation, line endings)
+ * when modifying JSON files using jsonc-parser's surgical edit operations.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as JsonPatch from "effect/JsonPatch";
+import type * as Schema from "effect/Schema";
+/**
+ * A single JSON modification: set or remove a value at a path.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface JsonModification {
+    readonly path: ReadonlyArray<string | number>;
+    readonly value: unknown;
+}
+export type JsonPointerPathResult = {
+    readonly _tag: "Success";
+    readonly path: ReadonlyArray<string | number>;
+} | {
+    readonly _tag: "Failure";
+    readonly reason: "invalid_pointer" | "untranslatable_pointer";
+};
+export interface ApplyJsonPatchOptions {
+    readonly getInsertionIndex?: (path: ReadonlyArray<string | number>, properties: ReadonlyArray<string>) => number;
+}
+export type JsonPatchTextResult = {
+    readonly _tag: "Success";
+    readonly text: string;
+} | {
+    readonly _tag: "Failure";
+    readonly reason: "invalid_pointer" | "untranslatable_pointer" | "edit_failed";
+};
+export declare const jsonPointerToJsonPath: (pointer: string, document: Schema.Json) => JsonPointerPathResult;
+export declare const applyJsonPatchToText: (text: string, document: Schema.Json, patch: JsonPatch.JsonPatch, options?: ApplyJsonPatchOptions) => JsonPatchTextResult;
+//# sourceMappingURL=format-preserving-json.d.ts.map