@shipworthy/openapi-overlay 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipworthy AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,271 @@
-# Temporary Holding Version
+# @shipworthy/openapi-overlay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Apply OpenAPI Overlay 1.0 and 1.1 documents with Effect v4. Validation schemas are generated
+from the upstream YAML schemas, and action behavior follows the declared feature version. Supports RFC 9535 JSONPath, sequential `update`, `copy`, and `remove`
+actions, recursive object merges, array concatenation/appending, and primitive replacement.
+
+## Installation
+
+```sh
+bun add @shipworthy/openapi-overlay effect@4.1.4
+```
+
+Requires Node.js 22.19.0 or later, or Bun. Ships ESM JavaScript and TypeScript declarations.
+
+## Usage
+
+```ts
+import { applyOverlay } from "@shipworthy/openapi-overlay";
+import { Effect } from "effect";
+
+const document = {
+  openapi: "3.1.0",
+  info: { title: "Pets", version: "1.0.0" },
+  paths: {},
+};
+
+const overlay = {
+  overlay: "1.1.0",
+  info: { title: "Public documentation", version: "1.0.0" },
+  actions: [
+    { target: "$.info.title", update: "Public Pets" },
+    { target: "$", update: { "x-public": true } },
+  ],
+};
+
+const result = await Effect.runPromise(applyOverlay(document, overlay));
+// result.info.title is "Public Pets"; document is unchanged.
+```
+
+`applyOverlay(document, overlay, options?)` accepts either a parsed object or JSON/YAML text for
+the document and overlay. Options are schema-validated: `removeUnusedComponents` is an optional
+boolean, and unknown options are rejected with `OverlayError`. The options type is inferred
+from its Effect Schema. It returns `Effect.Effect<Schema.MutableJsonObject, OverlayError>` without requiring
+services. Input documents must be JSON-compatible objects. Inputs are validated with Effect
+schemas and copied before applying actions; neither input is mutated, including on failure.
+
+`applyOverlayWithWarnings(document, overlay, options?)` accepts the same inputs and returns
+`{ document, warnings }`. Each warning contains the one-based `action` number, `target`, and
+`message`. Unmatched targets and malformed JSONPath target expressions are skipped and
+collected in action order; subsequent actions still run against the preceding result.
+`applyOverlay` returns only the document. Neither function logs warnings.
+
+```ts
+import { applyOverlayWithWarnings } from "@shipworthy/openapi-overlay";
+
+const { document: updated, warnings } = await Effect.runPromise(
+  applyOverlayWithWarnings(document, overlay),
+);
+```
+
+By default, the function applies overlays without validating the resulting OpenAPI structure.
+It does not load files or fetch URLs. `extends` is descriptive
+metadata; callers choose the document explicitly. To bundle and upgrade first, use
+`bundleDocument` from `@shipworthy/openapi-parser`, then pass the result to `applyOverlay`.
+
+### Filtering operations and removing unused components
+
+Use an Overlay removal action to select operations by `operationId`, then opt into pruning:
+
+```ts
+const selected = {
+  overlay: "1.1.0",
+  info: { title: "Selected operations", version: "1.0.0" },
+  actions: [
+    {
+      target:
+        "$.paths.*[?(@.responses && !(@.operationId == 'listPets' || @.operationId == 'getPet'))]",
+      remove: true,
+    },
+  ],
+};
+
+const result = await Effect.runPromise(
+  applyOverlay(document, selected, { removeUnusedComponents: true }),
+);
+```
+
+This selector identifies operations by their `responses` field. For operations without that
+field, use method-specific selectors. Pruning runs after all actions, removes paths without
+operations, and keeps the transitive component dependencies of remaining paths, webhooks,
+document-level security, and retained root `$defs`. It handles all component categories, recursive schemas,
+discriminator mappings and inheritance, and security scheme names. Example payloads,
+schema defaults, and extension values do not count as references. Empty component groups
+are removed; component extensions are preserved.
+
+Pruning requires a bundled OpenAPI 3.1 document with local JSON Pointer references. Bundle
+and upgrade with `bundleDocument` first; the CLI does this automatically. Reachable external
+or anchor references and `$dynamicRef` are rejected. Broken references or links to removed
+operation IDs fail with `OverlayError`. Neither input is mutated. Without the option,
+unused components and paths are retained and no OpenAPI validation is performed.
+
+## Actions
+
+- Actions run in order against the result of the previous action. A target that selects no
+  nodes succeeds without creating anything. To create a property, target its existing parent
+  and merge the new property into it.
+- Object updates merge recursively. Existing properties remain unless replaced or removed.
+  Corresponding arrays concatenate; corresponding primitives replace each other, including
+  `null`. Other corresponding property categories are incompatible and fail.
+- In 1.1, array targets concatenate an array update or append an object or primitive update as
+  one element. Primitive targets require primitive updates.
+- In 1.0, targets must select objects or arrays; primitive targets fail, including for removal.
+  A selected array receives the update as one appended entry, including when that entry is an
+  array. Update primitive properties through their containing object.
+- In 1.1, `copy` selects exactly one source node from the current document and applies a snapshot of
+  its value using the same merge rules. Copies are independent of the source and other targets.
+- In 1.1, multiple update/copy targets must all be objects, all arrays, or all primitives. Different
+  primitive types belong to the same category.
+- `remove: true` takes precedence over `update` and `copy`. Array removals use the original
+  selected indexes. Removing the document root fails because it has no containing map or array.
+- Supplying both `update` and `copy` on a matching action without `remove: true` fails as
+  ambiguous. An action with no modifier has no effect. Duplicate target locations are modified
+  once per action.
+
+Versions `1.0.x` and `1.1.x` use their respective schemas and action behavior. Patch versions
+do not change the feature set. `copy` and `info.description` are accepted only in 1.1. Both
+versions require at least one action and reject structurally duplicate actions, as specified
+by the upstream schemas. Unknown feature versions fail. YAML is parsed with
+[Effect's YAML 1.2 parser](https://effect.website/docs/v4/api/effect/encoding/Yaml).
+JSON-incompatible values and duplicate YAML mapping keys are rejected. The parser does not
+support compact nested block sequences (`- - value`), multiline flow collections, explicit
+complex keys, tag/directive processing, recursive aliases, or document streams. Use expanded
+block collections for nested YAML; formatted JSON is accepted. Comments and source formatting
+are not retained.
+
+## Preparing a document for generation
+
+Apply an overlay before running a generator so the same document changes are available to
+TypeScript types, runtime validators, and clients:
+
+```sh
+openapi overlay openapi.yaml --overlay types.overlay.yaml -o types.openapi.json
+openapi generate typescript -i types.openapi.json -o src/generated
+```
+
+The examples below assume the named schemas and paths exist. Target an existing parent to add
+a property; an unmatched target has no effect. Updates contain literal values, so list property
+and parameter names explicitly.
+
+### Require properties
+
+Add property names to `required`. A property's `default` alone does not require its presence
+in generated TypeScript types; the default remains available as documentation.
+
+```yaml
+overlay: 1.1.0
+info: { title: Required pet properties, version: "1" }
+actions:
+  - target: $.components.schemas.Pet
+    update: { required: [id, name] }
+```
+
+This appends to an existing `required` list. To replace the list, first remove
+`$.components.schemas.Pet.required`, then update its parent with the new list.
+
+### Allow additional keys
+
+Set `additionalProperties: true` on the intended object schemas, including empty object
+schemas. The TypeScript generator emits an index signature with `unknown` values.
+
+```yaml
+overlay: 1.1.0
+info: { title: Open object schemas, version: "1" }
+actions:
+  - target: $.components.schemas.Pet
+    update: { additionalProperties: true }
+  - target: $.components.schemas.Metadata
+    update: { additionalProperties: true }
+```
+
+Preserve existing schema-valued `additionalProperties` constraints when they should still
+apply. To replace a schema-valued constraint with `true`, remove the `additionalProperties`
+property first, then update its parent; object and boolean values cannot merge.
+
+### Remove deprecated members
+
+Use a filter to remove properties or parameters marked `deprecated: true`, and remove
+individual operations by their path and method:
+
+```yaml
+overlay: 1.1.0
+info: { title: Public pet API, version: "1" }
+actions:
+  - target: $.components.schemas.Pet.properties[?@.deprecated == true]
+    remove: true
+  - target: $.components.schemas.Pet.required[?@ == 'legacy']
+    remove: true
+  - target: $.paths['/pets/{id}'].get.parameters[?@.deprecated == true]
+    remove: true
+  - target: $.paths['/pets/{id}'].delete
+    remove: true
+```
+
+Here `legacy` is a deprecated property listed in `Pet.required`. Remove each corresponding
+`required` entry when removing a property. Filters inspect the selected object, not the target
+of a `$ref`; handle referenced deprecated members explicitly. When removing a component,
+repair or remove references to it as well.
+
+### Declare path parameters
+
+Add a required parameter declaration for each placeholder in a path template. This example
+adds `id` to the path item's parameters, making it available to all operations on that path:
+
+```yaml
+overlay: 1.1.0
+info: { title: Pet path parameters, version: "1" }
+actions:
+  - target: $.paths['/pets/{id}']
+    update:
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string }
+```
+
+Parameter arrays append on update, so add declarations only for parameters that are missing.
+
+## Schemas and errors
+
+The public API exports `applyOverlay`, `applyOverlayWithWarnings`, `OverlayError`, and the Effect schemas `Overlay`,
+`OverlayInfo`, and `OverlayAction`, each with its schema-inferred TypeScript type of the same name.
+Schema objects allow `x-` specification extensions and reject other undeclared fields. The root
+schemas accept the union of supported versions. Import a particular version to validate or type
+its documents directly:
+
+```ts
+import { Overlay, type OverlayAction } from "@shipworthy/openapi-overlay/schemas/1.0";
+// Also available at @shipworthy/openapi-overlay/schemas/1.1.
+```
+
+```ts
+import { Overlay } from "@shipworthy/openapi-overlay";
+import { Schema } from "effect";
+
+const checked = Schema.decodeUnknownEffect(Overlay)({
+  overlay: "1.1.0",
+  info: { title: "Public documentation", version: "1.0.0" },
+  actions: [{ target: "$", update: {} }],
+});
+```
+
+`OverlayError` contains `message` and an optional `cause`. Action failures also contain a
+one-based `action` index and the `target` expression. Catch it with
+`Effect.catchTag("OverlayError", handler)`.
+
+## CLI
+
+Install `@shipworthy/openapi-cli` to bundle a local or remote OpenAPI document before overlaying:
+
+```sh
+openapi overlay openapi.yaml --overlay overlay.yaml -o bundled.openapi.json
+openapi overlay openapi.yaml --overlay selected.overlay.yaml --remove-unused-components -o selected.openapi.json
+```
+
+The CLI resolves external references and upgrades OpenAPI 3.0 to 3.1, then applies the overlay
+and writes formatted JSON. See the [CLI documentation](../openapi-cli/README.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/apply.d.ts

@@ -0,0 +1,17 @@
+import { Effect, Schema } from "effect";
+import { OverlayError } from "./errors.ts";
+/** Apply actions and collect invalid or unmatched targets without mutating inputs. */
+export declare const applyOverlayWithWarnings: (document: unknown, overlay: unknown, options?: {
+    readonly removeUnusedComponents?: boolean | undefined;
+} | undefined) => Effect.Effect<{
+    document: Schema.MutableJsonObject;
+    warnings: {
+        readonly action: number;
+        readonly target: string;
+        readonly message: string;
+    }[];
+}, OverlayError, never>;
+/** Apply version-specific Overlay actions without mutating inputs. */
+export declare const applyOverlay: (document: unknown, overlay: unknown, options?: {
+    readonly removeUnusedComponents?: boolean | undefined;
+} | undefined) => Effect.Effect<Schema.MutableJsonObject, OverlayError, never>;

package/dist/apply.js

@@ -0,0 +1,206 @@
+import { Array as Arr, Effect, Formatter, Option, pipe, Predicate, Record, Result, Schema, String as Str, } from "effect";
+import * as Yaml from "effect/encoding/Yaml";
+import { exec } from "jsonpath-rfc9535";
+import { OverlayError } from "./errors.js";
+import { removeUnusedComponents } from "./prune.js";
+import { Overlay } from "./schemas.js";
+const applyOverlayOptions = Schema.Struct({
+    removeUnusedComponents: Schema.optionalKey(Schema.Boolean),
+});
+const overlayWarning = Schema.Struct({
+    action: Schema.Int,
+    target: Schema.String,
+    message: Schema.String,
+});
+function applyIfEnabled(enabled, transform) {
+    return Effect.flatMap((document) => Effect.suspend(() => transform(document)).pipe(Effect.when(Effect.succeed(enabled === true)), Effect.map(Option.getOrElse(() => document))));
+}
+const parseInput = Effect.fnUntraced(function* (input, label) {
+    if (typeof input !== "string")
+        return input;
+    return yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown))(input).pipe(Effect.catch(() => Effect.try({
+        try: () => Yaml.parse(input),
+        catch: (cause) => new OverlayError({ message: `Invalid ${label}: ${String(cause)}`, cause }),
+    })));
+});
+function cloneObject(value) {
+    return Record.fromEntries(Arr.map(Record.toEntries(value), ([key, item]) => [key, clone(item)]));
+}
+function clone(value) {
+    if (Arr.isArray(value))
+        return Arr.map(value, clone);
+    if (Predicate.isObject(value))
+        return cloneObject(value);
+    return value;
+}
+function kind(value) {
+    if (Arr.isArray(value))
+        return "array";
+    return Predicate.isObject(value) ? "object" : "primitive";
+}
+function merge(target, update, append = false) {
+    if (Arr.isArray(target)) {
+        if (!Arr.isArray(update) && !append) {
+            throw new TypeError("Incompatible array property");
+        }
+        const items = Arr.isArray(update) ? update : [update];
+        for (const item of items)
+            target.push(clone(item));
+        return target;
+    }
+    if (Predicate.isObject(target)) {
+        if (kind(update) !== "object")
+            throw new TypeError("An object target requires an object update");
+        const object = target;
+        for (const [key, value] of Record.toEntries(update)) {
+            const next = Record.has(object, key)
+                ? merge(object[key], value)
+                : clone(value);
+            Object.defineProperty(target, key, {
+                value: next,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+        }
+        return target;
+    }
+    if (kind(update) !== "primitive")
+        throw new TypeError("A primitive target requires a primitive update");
+    return clone(update);
+}
+function select(document, expression) {
+    const nodes = [];
+    exec(document, expression, (value, path) => {
+        let parent = document;
+        for (const key of path.slice(0, -1)) {
+            parent = Arr.isArray(parent)
+                ? parent[Number(key)]
+                : parent[key];
+        }
+        nodes.push({
+            value,
+            path: [...path],
+            parent: path.length === 0 ? undefined : parent,
+            key: path.at(-1),
+        });
+    });
+    return nodes;
+}
+function uniqueNodes(nodes) {
+    return [
+        ...new Map(Arr.map(nodes, (node) => [Formatter.formatJson(node.path), node])).values(),
+    ];
+}
+function remove(nodes) {
+    if (Arr.some(nodes, (node) => node.parent === undefined)) {
+        throw new TypeError("Cannot remove the document root, which has no containing map or array");
+    }
+    // Descendants first; descending array indexes preserve the original selection.
+    const ordered = uniqueNodes(nodes).sort((left, right) => right.path.length - left.path.length ||
+        (typeof left.key === "number" && typeof right.key === "number"
+            ? right.key - left.key
+            : typeof left.key === "number"
+                ? -1
+                : typeof right.key === "number"
+                    ? 1
+                    : 0));
+    for (const { parent, key } of ordered) {
+        if (Arr.isArray(parent))
+            parent.splice(Number(key), 1);
+        else if (parent !== undefined && key !== undefined)
+            delete parent[key];
+    }
+}
+function applyAction(document, action, version, nodes) {
+    if (version !== "1.0" && version !== "1.1") {
+        throw new TypeError(`Overlay ${version} action behavior is not implemented`);
+    }
+    if (version === "1.0" && Arr.some(nodes, (node) => kind(node.value) === "primitive")) {
+        throw new TypeError("Overlay 1.0 targets must select objects or arrays, not primitives");
+    }
+    if (action.remove === true) {
+        remove(nodes);
+        return;
+    }
+    const hasUpdate = Record.has(action, "update");
+    const copy = version === "1.1" && typeof action.copy === "string" ? action.copy : undefined;
+    if (hasUpdate && copy !== undefined) {
+        throw new TypeError("An action cannot contain both update and copy");
+    }
+    if (!hasUpdate && copy === undefined)
+        return;
+    if (version === "1.1" && new Set(Arr.map(nodes, (node) => kind(node.value))).size > 1) {
+        throw new TypeError("All selected nodes must be objects, arrays, or primitives of the same category");
+    }
+    let update = action.update;
+    if (copy !== undefined) {
+        const sources = select(document, copy);
+        if (sources.length !== 1)
+            throw new TypeError("copy must select exactly one source node");
+        update = clone(sources[0].value);
+    }
+    for (const node of uniqueNodes(nodes)) {
+        if (version === "1.0" && Arr.isArray(node.value)) {
+            node.value.push(clone(update));
+            continue;
+        }
+        const value = merge(node.value, update, true);
+        if (Arr.isArray(node.parent))
+            node.parent[Number(node.key)] = value;
+        else if (node.parent !== undefined && node.key !== undefined) {
+            Object.defineProperty(node.parent, node.key, {
+                value,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+        }
+    }
+}
+/** Apply actions and collect invalid or unmatched targets without mutating inputs. */
+export const applyOverlayWithWarnings = Effect.fn("applyOverlayWithWarnings")(function* (document, overlay, options = {}) {
+    const checkedOptions = yield* Schema.decodeEffect(applyOverlayOptions)(options, {
+        onExcessProperty: "error",
+    }).pipe(Effect.mapError((cause) => new OverlayError({ message: `Invalid options: ${cause.message}`, cause })));
+    const source = yield* Schema.decodeUnknownEffect(Schema.JsonObject)(yield* parseInput(document, "document")).pipe(Effect.mapError((cause) => new OverlayError({ message: `Invalid document: ${cause.message}`, cause })));
+    const parsed = yield* Schema.decodeUnknownEffect(Overlay)(yield* parseInput(overlay, "overlay"), {
+        onExcessProperty: "error",
+    }).pipe(Effect.mapError((cause) => new OverlayError({ message: `Invalid overlay: ${cause.message}`, cause })));
+    const result = cloneObject(source);
+    const version = pipe(parsed.overlay, Str.split("."), Arr.take(2), Arr.join("."));
+    const warnings = yield* Effect.forEach(parsed.actions, Effect.fnUntraced(function* (action, index) {
+        const selected = yield* Effect.try({
+            try: () => select(result, action.target),
+            catch: (cause) => ({
+                action: index + 1,
+                target: action.target,
+                message: `Invalid target: ${String(cause)}`,
+            }),
+        }).pipe(Effect.result);
+        if (Result.isFailure(selected))
+            return [selected.failure];
+        if (selected.success.length === 0)
+            return [
+                {
+                    action: index + 1,
+                    target: action.target,
+                    message: "Target matched no nodes",
+                },
+            ];
+        yield* Effect.try({
+            try: () => applyAction(result, action, version, selected.success),
+            catch: (cause) => new OverlayError({
+                message: `Overlay action ${index + 1} (${action.target}): ${String(cause)}`,
+                action: index + 1,
+                target: action.target,
+                cause,
+            }),
+        });
+        return [];
+    }));
+    const output = yield* Effect.succeed(result).pipe(applyIfEnabled(checkedOptions.removeUnusedComponents, removeUnusedComponents));
+    return { document: output, warnings: Arr.flatten(warnings) };
+});
+/** Apply version-specific Overlay actions without mutating inputs. */
+export const applyOverlay = Effect.fn("applyOverlay")((document, overlay, options = {}) => applyOverlayWithWarnings(document, overlay, options).pipe(Effect.map((result) => result.document)));

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+declare const OverlayError_base: Schema.Class<OverlayError, Schema.TaggedStruct<"OverlayError", {
+    readonly message: Schema.String;
+    readonly action: Schema.optionalKey<Schema.Int>;
+    readonly target: Schema.optionalKey<Schema.String>;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+export declare class OverlayError extends OverlayError_base {
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+export class OverlayError extends Schema.TaggedError()("OverlayError", {
+    message: Schema.String,
+    action: Schema.optionalKey(Schema.Int),
+    target: Schema.optionalKey(Schema.String),
+    cause: Schema.optionalKey(Schema.Defect()),
+}) {
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { applyOverlay, applyOverlayWithWarnings } from "./apply.ts";
+export { OverlayError } from "./errors.ts";
+export { Overlay, OverlayAction, OverlayInfo } from "./schemas.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { applyOverlay, applyOverlayWithWarnings } from "./apply.js";
+export { OverlayError } from "./errors.js";
+export { Overlay, OverlayAction, OverlayInfo } from "./schemas.js";

package/dist/prune.d.ts

@@ -0,0 +1,3 @@
+import { Effect, Schema } from "effect";
+import { OverlayError } from "./errors.ts";
+export declare const removeUnusedComponents: (document: Schema.MutableJsonObject) => Effect.Effect<Schema.MutableJsonObject, OverlayError, never>;

package/dist/prune.js

@@ -0,0 +1,239 @@
+import { OpenApiCallback, OpenApiExample, OpenApiHeader, OpenApiHttpMethod, OpenApiLink, OpenApiMediaType, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiReference, OpenApiResponse, OpenApiSchema, OpenApiSecurityScheme, ParsedOpenApi, } from "@shipworthy/openapi-parser/schemas/3.1";
+import { Array, Effect, JsonPointer, pipe, Predicate, Record, Schema, String } from "effect";
+import { OverlayError } from "./errors.js";
+const methods = OpenApiHttpMethod.literals;
+const schemaWithAllOf = Schema.Struct({ allOf: Schema.Array(OpenApiSchema) });
+const schemaMaps = ["properties", "patternProperties", "$defs", "dependentSchemas"];
+const schemaLists = ["allOf", "anyOf", "oneOf", "prefixItems"];
+const schemaSingles = [
+    "additionalProperties",
+    "unevaluatedProperties",
+    "items",
+    "contains",
+    "not",
+    "if",
+    "then",
+    "else",
+    "propertyNames",
+    "unevaluatedItems",
+    "contentSchema",
+];
+function extendsSchema(schema, pointer) {
+    return (Schema.is(schemaWithAllOf)(schema) &&
+        Array.some(schema.allOf, (child) => Schema.is(OpenApiReference)(child) && child.$ref === pointer));
+}
+function visitMap(values, visit, ignoreExtensions = false) {
+    return Effect.forEach(Record.toEntries(values ?? {}), ([key, value]) => ignoreExtensions && pipe(key, String.startsWith("x-")) ? Effect.void : visit(value), { discard: true });
+}
+export const removeUnusedComponents = Effect.fnUntraced(function* (document) {
+    const parsed = yield* Schema.decodeUnknownEffect(ParsedOpenApi)(document);
+    const used = new Set();
+    const followed = new Set();
+    const removedPaths = new Set();
+    const components = new Map();
+    const operationIds = new Set();
+    const linkedOperationIds = new Set();
+    const inherited = new Set();
+    const componentPointer = (category, name) => JsonPointer.formatUriFragment(["components", category, name]);
+    const mark = Effect.fnUntraced(function* (category, name) {
+        const pointer = componentPointer(category, name);
+        if (used.has(pointer))
+            return;
+        const visit = components.get(pointer);
+        if (visit === undefined)
+            return yield* new OverlayError({ message: `Missing component ${pointer}` });
+        used.add(pointer);
+        yield* visit();
+    });
+    const reference = Effect.fnUntraced(function* (ref, visit) {
+        const tokens = pipe(ref, String.startsWith("#/"))
+            ? JsonPointer.parseUriFragment(ref)
+            : undefined;
+        if (tokens === undefined)
+            return yield* new OverlayError({
+                message: `Component pruning requires bundled local JSON Pointer references: ${ref}`,
+            });
+        if (tokens[0] === "paths" && tokens[1] !== undefined && removedPaths.has(tokens[1]))
+            return yield* new OverlayError({ message: `Reference targets a removed path: ${ref}` });
+        const root = parsed;
+        const target = Array.reduce(tokens, root, (value, token) => Predicate.isObject(value) && Record.has(value, token) ? value[token] : undefined);
+        if (target === undefined)
+            return yield* new OverlayError({ message: `Missing reference ${ref}` });
+        if (followed.has(ref))
+            return;
+        followed.add(ref);
+        if (tokens[0] === "components" && tokens[1] !== undefined && tokens[2] !== undefined)
+            yield* mark(tokens[1], tokens[2]);
+        yield* visit(target);
+    });
+    function referenced(schema, walk) {
+        const visit = Effect.fnUntraced(function* (value) {
+            if (Predicate.isObject(value) && Predicate.isString(value.$ref)) {
+                yield* reference(value.$ref, visit);
+                return;
+            }
+            yield* walk(yield* Schema.decodeUnknownEffect(schema)(value));
+        });
+        return visit;
+    }
+    const visitSchema = Effect.fnUntraced(function* (value, componentName) {
+        const schema = yield* Schema.decodeUnknownEffect(OpenApiSchema)(value);
+        if (typeof schema === "boolean")
+            return;
+        if (Predicate.isString(schema.$ref))
+            yield* reference(schema.$ref, visitSchema);
+        if (Predicate.isString(schema.$dynamicRef))
+            return yield* new OverlayError({
+                message: `Component pruning does not support $dynamicRef: ${schema.$dynamicRef}`,
+            });
+        yield* Effect.forEach(schemaSingles, (key) => (schema[key] === undefined ? Effect.void : visitSchema(schema[key])), { discard: true });
+        yield* Effect.forEach(schemaLists, (key) => {
+            const children = schema[key];
+            return Array.isArray(children)
+                ? Effect.forEach(children, (child) => visitSchema(child), { discard: true })
+                : Effect.void;
+        }, { discard: true });
+        yield* Effect.forEach(schemaMaps, (key) => {
+            const children = schema[key];
+            return Predicate.isObject(children)
+                ? Effect.forEach(Record.values(children), (child) => visitSchema(child), {
+                    discard: true,
+                })
+                : Effect.void;
+        }, { discard: true });
+        const discriminator = schema.discriminator;
+        if (Predicate.isObject(discriminator) && componentName !== undefined)
+            yield* visitDerivedSchemas(componentName);
+        if (Predicate.isObject(discriminator) && Predicate.isObject(discriminator.mapping))
+            yield* Effect.forEach(Record.values(discriminator.mapping), (target) => {
+                if (!Predicate.isString(target))
+                    return Effect.void;
+                return Record.has(parsed.components?.schemas ?? {}, target)
+                    ? mark("schemas", target)
+                    : reference(target, visitSchema);
+            }, { discard: true });
+    });
+    function visitDerivedSchemas(parent) {
+        if (inherited.has(parent))
+            return Effect.void;
+        inherited.add(parent);
+        const pointer = componentPointer("schemas", parent);
+        return Effect.forEach(Record.toEntries(parsed.components?.schemas ?? {}), ([name, schema]) => {
+            if (!extendsSchema(schema, pointer))
+                return Effect.void;
+            return mark("schemas", name).pipe(Effect.andThen(() => visitDerivedSchemas(name)));
+        }, { discard: true });
+    }
+    const visitExample = referenced(OpenApiExample, () => Effect.void);
+    const visitSecurityScheme = referenced(OpenApiSecurityScheme, () => Effect.void);
+    const visitHeader = referenced(OpenApiHeader, Effect.fnUntraced(function* (header) {
+        if (header.schema !== undefined)
+            yield* visitSchema(header.schema);
+        yield* visitMap(header.content, visitMediaType);
+        yield* visitMap(header.examples, visitExample);
+    }));
+    const visitParameter = referenced(OpenApiParameter, Effect.fnUntraced(function* (parameter) {
+        if (parameter.schema !== undefined)
+            yield* visitSchema(parameter.schema);
+        yield* visitMap(parameter.content, visitMediaType);
+        yield* visitMap(parameter.examples, visitExample);
+    }));
+    const visitRequestBody = referenced(OpenApiRequestBody, (body) => visitMap(body.content, visitMediaType));
+    const visitLink = referenced(OpenApiLink, Effect.fnUntraced(function* (link) {
+        if (link.operationId !== undefined)
+            linkedOperationIds.add(link.operationId);
+        if (link.operationRef !== undefined && pipe(link.operationRef, String.startsWith("#")))
+            yield* reference(link.operationRef, visitOperation);
+    }));
+    const visitResponse = referenced(OpenApiResponse, Effect.fnUntraced(function* (response) {
+        yield* visitMap(response.content, visitMediaType);
+        yield* visitMap(response.headers, visitHeader);
+        yield* visitMap(response.links, visitLink);
+    }));
+    const visitCallback = referenced(OpenApiCallback, (callback) => visitMap(callback, visitPathItem, true));
+    function visitMediaType(value) {
+        return Schema.decodeUnknownEffect(OpenApiMediaType)(value).pipe(Effect.flatMap(Effect.fnUntraced(function* (media) {
+            if (media.schema !== undefined)
+                yield* visitSchema(media.schema);
+            yield* visitMap(media.examples, visitExample);
+            yield* Effect.forEach(Record.values(media.encoding ?? {}), (encoding) => visitMap(encoding.headers, visitHeader), { discard: true });
+        })));
+    }
+    function visitSecurity(security) {
+        return Effect.forEach(security ?? [], (requirement) => Effect.forEach(Record.keys(requirement), (name) => mark("securitySchemes", name), {
+            discard: true,
+        }), { discard: true });
+    }
+    function visitOperation(value) {
+        return Schema.decodeUnknownEffect(OpenApiOperation)(value).pipe(Effect.flatMap(Effect.fnUntraced(function* (operation) {
+            if (operation.operationId !== undefined)
+                operationIds.add(operation.operationId);
+            yield* Effect.forEach(operation.parameters ?? [], visitParameter, { discard: true });
+            if (operation.requestBody !== undefined)
+                yield* visitRequestBody(operation.requestBody);
+            yield* visitMap(operation.responses, visitResponse, true);
+            yield* visitMap(operation.callbacks, visitCallback);
+            yield* visitSecurity(operation.security);
+        })));
+    }
+    function visitPathItem(value) {
+        return Schema.decodeUnknownEffect(OpenApiPathItem)(value).pipe(Effect.flatMap(Effect.fnUntraced(function* (item) {
+            if (item.$ref !== undefined)
+                yield* reference(item.$ref, visitPathItem);
+            yield* Effect.forEach(item.parameters ?? [], visitParameter, { discard: true });
+            yield* Effect.forEach(methods, (method) => (item[method] === undefined ? Effect.void : visitOperation(item[method])), { discard: true });
+        })));
+    }
+    function register(category, values, visit) {
+        Array.forEach(Record.toEntries(values ?? {}), ([name, value]) => {
+            components.set(componentPointer(category, name), () => visit(value));
+        });
+    }
+    Array.forEach(Record.toEntries(parsed.components?.schemas ?? {}), ([name, schema]) => {
+        components.set(componentPointer("schemas", name), () => visitSchema(schema, name));
+    });
+    register("responses", parsed.components?.responses, visitResponse);
+    register("parameters", parsed.components?.parameters, visitParameter);
+    register("requestBodies", parsed.components?.requestBodies, visitRequestBody);
+    register("headers", parsed.components?.headers, visitHeader);
+    register("examples", parsed.components?.examples, visitExample);
+    register("links", parsed.components?.links, visitLink);
+    register("callbacks", parsed.components?.callbacks, visitCallback);
+    register("pathItems", parsed.components?.pathItems, visitPathItem);
+    register("securitySchemes", parsed.components?.securitySchemes, visitSecurityScheme);
+    const retainedPaths = yield* Effect.forEach(Record.toEntries(parsed.paths ?? {}), Effect.fnUntraced(function* ([path, value]) {
+        if (pipe(path, String.startsWith("x-")))
+            return;
+        const item = yield* Schema.decodeEffect(OpenApiPathItem)(value);
+        if (item.$ref !== undefined || Array.some(methods, (method) => item[method] !== undefined))
+            return item;
+        removedPaths.add(path);
+    }));
+    yield* Effect.forEach(retainedPaths, (item) => (item === undefined ? Effect.void : visitPathItem(item)), { discard: true });
+    yield* visitMap(parsed.webhooks, visitPathItem);
+    yield* visitMap(parsed.$defs, (value) => visitSchema(value));
+    yield* visitSecurity(parsed.security);
+    yield* Effect.forEach(linkedOperationIds, (id) => operationIds.has(id)
+        ? Effect.void
+        : new OverlayError({ message: `Missing linked operationId ${id}` }), { discard: true });
+    const paths = document.paths;
+    if (Predicate.isObject(paths) && !Array.isArray(paths))
+        Array.forEach(removedPaths, (path) => {
+            delete paths[path];
+        });
+    const maps = document.components;
+    if (Predicate.isObject(maps) && !Array.isArray(maps))
+        Array.forEach(Record.toEntries(maps), ([category, entries]) => {
+            if (pipe(category, String.startsWith("x-")) ||
+                !Predicate.isObject(entries) ||
+                Array.isArray(entries))
+                return;
+            Array.forEach(Record.keys(entries), (name) => {
+                if (!used.has(componentPointer(category, name)))
+                    delete entries[name];
+            });
+            if (Record.keys(entries).length === 0)
+                delete maps[category];
+        });
+    return document;
+}, Effect.mapError((cause) => new OverlayError({ message: `Cannot prune components: ${cause.message}`, cause })));

package/dist/schemas/1.0.d.ts

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+export declare const OverlayInfo: Schema.StructWithRest<Schema.Struct<{
+    readonly title: Schema.String;
+    readonly version: Schema.String;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+export type OverlayInfo = typeof OverlayInfo.Type;
+export declare const OverlayAction: Schema.StructWithRest<Schema.Struct<{
+    readonly target: Schema.String;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly update: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.Finite, Schema.Null]>>;
+    readonly remove: Schema.optionalKey<Schema.Boolean>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+export type OverlayAction = typeof OverlayAction.Type;
+export declare const Overlay: Schema.StructWithRest<Schema.Struct<{
+    readonly overlay: Schema.String;
+    readonly info: Schema.StructWithRest<Schema.Struct<{
+        readonly title: Schema.String;
+        readonly version: Schema.String;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+    readonly extends: Schema.optionalKey<Schema.String>;
+    readonly actions: Schema.$Array<Schema.StructWithRest<Schema.Struct<{
+        readonly target: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+        readonly update: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.Finite, Schema.Null]>>;
+        readonly remove: Schema.optionalKey<Schema.Boolean>;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+export type Overlay = typeof Overlay.Type;

package/dist/schemas/1.0.js

@@ -0,0 +1,52 @@
+// Generated from schemas/v1.0/schema.yaml (sha256: 209a9755d58f96b5d80bf5a3ed4f6f2b9e77550fa27849cd67bd50bc3eabfa83).
+// Run bun run generate:schemas to regenerate. Do not edit by hand.
+import { Schema } from "effect";
+export const OverlayInfo = Schema.StructWithRest(Schema.Struct({ title: Schema.String, version: Schema.String }), [Schema.Record(Schema.String, Schema.Json.annotate({ expected: "JSON value" }))]).check(Schema.isPropertyNames(Schema.Union([
+    Schema.Literals(["title", "version"]),
+    Schema.String.check(Schema.isPattern(new globalThis.RegExp("^x-", "u")).annotate({
+        expected: "a string matching the RegExp ^x-",
+    })),
+])).annotate({
+    expected: "an object with property names matching the schema",
+    identifier: "OverlayInfo",
+}));
+export const OverlayAction = Schema.StructWithRest(Schema.Struct({
+    target: Schema.String.check(Schema.isPattern(new globalThis.RegExp("^\\$", "u")).annotate({
+        expected: "a string matching the RegExp ^\\$",
+    })),
+    description: Schema.optionalKey(Schema.String),
+    update: Schema.optionalKey(Schema.Union([
+        Schema.String,
+        Schema.Boolean,
+        Schema.Record(Schema.String, Schema.Json.annotate({ expected: "JSON value" })),
+        Schema.Array(Schema.Json.annotate({ expected: "JSON value" })),
+        Schema.Finite,
+        Schema.Null,
+    ])),
+    remove: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+}), [Schema.Record(Schema.String, Schema.Json.annotate({ expected: "JSON value" }))]).check(Schema.isPropertyNames(Schema.Union([
+    Schema.Literals(["target", "description", "update", "remove"]),
+    Schema.String.check(Schema.isPattern(new globalThis.RegExp("^x-", "u")).annotate({
+        expected: "a string matching the RegExp ^x-",
+    })),
+])).annotate({
+    expected: "an object with property names matching the schema",
+    identifier: "OverlayAction",
+}));
+export const Overlay = Schema.StructWithRest(Schema.Struct({
+    overlay: Schema.String.check(Schema.isPattern(new globalThis.RegExp("^1\\.0\\.\\d+$", "u")).annotate({
+        expected: "a string matching the RegExp ^1\\.0\\.\\d+$",
+    })),
+    info: OverlayInfo,
+    extends: Schema.optionalKey(Schema.String.annotate({ format: "uri-reference" })),
+    actions: Schema.Array(OverlayAction)
+        .check(Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }))
+        .check(Schema.isUnique().annotate({ expected: "an array with unique items" })),
+}), [Schema.Record(Schema.String, Schema.Json.annotate({ expected: "JSON value" }))])
+    .annotate({ description: "The description of Overlay v1.0.x documents" })
+    .check(Schema.isPropertyNames(Schema.Union([
+    Schema.Literals(["overlay", "info", "extends", "actions"]),
+    Schema.String.check(Schema.isPattern(new globalThis.RegExp("^x-", "u")).annotate({
+        expected: "a string matching the RegExp ^x-",
+    })),
+])).annotate({ expected: "an object with property names matching the schema" }));

package/dist/schemas/1.1.d.ts

@@ -0,0 +1,32 @@
+import { Schema } from "effect";
+export declare const OverlayInfo: Schema.StructWithRest<Schema.Struct<{
+    readonly title: Schema.String;
+    readonly version: Schema.String;
+    readonly description: Schema.optionalKey<Schema.String>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+export type OverlayInfo = typeof OverlayInfo.Type;
+export declare const OverlayAction: Schema.StructWithRest<Schema.Struct<{
+    readonly target: Schema.String;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly update: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.Finite, Schema.Null]>>;
+    readonly copy: Schema.optionalKey<Schema.String>;
+    readonly remove: Schema.optionalKey<Schema.Boolean>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+export type OverlayAction = typeof OverlayAction.Type;
+export declare const Overlay: Schema.StructWithRest<Schema.Struct<{
+    readonly overlay: Schema.String;
+    readonly info: Schema.StructWithRest<Schema.Struct<{
+        readonly title: Schema.String;
+        readonly version: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+    readonly extends: Schema.optionalKey<Schema.String>;
+    readonly actions: Schema.$Array<Schema.StructWithRest<Schema.Struct<{
+        readonly target: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+        readonly update: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.Finite, Schema.Null]>>;
+        readonly copy: Schema.optionalKey<Schema.String>;
+        readonly remove: Schema.optionalKey<Schema.Boolean>;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+export type Overlay = typeof Overlay.Type;

package/dist/schemas/1.1.js

@@ -0,0 +1,57 @@
+// Generated from schemas/v1.1/schema.yaml (sha256: c9988e3656d7f9de217654a3fc67b093c009668be357c86f07fd76b260863a51).
+// Run bun run generate:schemas to regenerate. Do not edit by hand.
+import { Schema } from "effect";
+export const OverlayInfo = Schema.StructWithRest(Schema.Struct({
+    title: Schema.String,
+    version: Schema.String,
+    description: Schema.optionalKey(Schema.String),
+}), [Schema.Record(Schema.String, Schema.Json.annotate({ expected: "JSON value" }))]).check(Schema.isPropertyNames(Schema.Union([
+    Schema.Literals(["title", "version", "description"]),
+    Schema.String.check(Schema.isPattern(new globalThis.RegExp("^x-", "u")).annotate({
+        expected: "a string matching the RegExp ^x-",
+    })),
+])).annotate({
+    expected: "an object with property names matching the schema",
+    identifier: "OverlayInfo",
+}));
+export const OverlayAction = Schema.StructWithRest(Schema.Struct({
+    target: Schema.String.check(Schema.isPattern(new globalThis.RegExp("^\\$", "u")).annotate({
+        expected: "a string matching the RegExp ^\\$",
+    })),
+    description: Schema.optionalKey(Schema.String),
+    update: Schema.optionalKey(Schema.Union([
+        Schema.String,
+        Schema.Boolean,
+        Schema.Record(Schema.String, Schema.Json.annotate({ expected: "JSON value" })),
+        Schema.Array(Schema.Json.annotate({ expected: "JSON value" })),
+        Schema.Finite,
+        Schema.Null,
+    ])),
+    copy: Schema.optionalKey(Schema.String),
+    remove: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+}), [Schema.Record(Schema.String, Schema.Json.annotate({ expected: "JSON value" }))]).check(Schema.isPropertyNames(Schema.Union([
+    Schema.Literals(["target", "description", "update", "copy", "remove"]),
+    Schema.String.check(Schema.isPattern(new globalThis.RegExp("^x-", "u")).annotate({
+        expected: "a string matching the RegExp ^x-",
+    })),
+])).annotate({
+    expected: "an object with property names matching the schema",
+    identifier: "OverlayAction",
+}));
+export const Overlay = Schema.StructWithRest(Schema.Struct({
+    overlay: Schema.String.check(Schema.isPattern(new globalThis.RegExp("^1\\.1\\.\\d+$", "u")).annotate({
+        expected: "a string matching the RegExp ^1\\.1\\.\\d+$",
+    })),
+    info: OverlayInfo,
+    extends: Schema.optionalKey(Schema.String.annotate({ format: "uri-reference" })),
+    actions: Schema.Array(OverlayAction)
+        .check(Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }))
+        .check(Schema.isUnique().annotate({ expected: "an array with unique items" })),
+}), [Schema.Record(Schema.String, Schema.Json.annotate({ expected: "JSON value" }))])
+    .annotate({ description: "The description of Overlay v1.1.x documents" })
+    .check(Schema.isPropertyNames(Schema.Union([
+    Schema.Literals(["overlay", "info", "extends", "actions"]),
+    Schema.String.check(Schema.isPattern(new globalThis.RegExp("^x-", "u")).annotate({
+        expected: "a string matching the RegExp ^x-",
+    })),
+])).annotate({ expected: "an object with property names matching the schema" }));

package/dist/schemas.d.ts

@@ -0,0 +1,53 @@
+import { Schema } from "effect";
+export declare const OverlayInfo: Schema.Union<readonly [Schema.StructWithRest<Schema.Struct<{
+    readonly title: Schema.String;
+    readonly version: Schema.String;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>, Schema.StructWithRest<Schema.Struct<{
+    readonly title: Schema.String;
+    readonly version: Schema.String;
+    readonly description: Schema.optionalKey<Schema.String>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>]>;
+export type OverlayInfo = typeof OverlayInfo.Type;
+export declare const OverlayAction: Schema.Union<readonly [Schema.StructWithRest<Schema.Struct<{
+    readonly target: Schema.String;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly update: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.Finite, Schema.Null]>>;
+    readonly remove: Schema.optionalKey<Schema.Boolean>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>, Schema.StructWithRest<Schema.Struct<{
+    readonly target: Schema.String;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly update: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.Finite, Schema.Null]>>;
+    readonly copy: Schema.optionalKey<Schema.String>;
+    readonly remove: Schema.optionalKey<Schema.Boolean>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>]>;
+export type OverlayAction = typeof OverlayAction.Type;
+export declare const Overlay: Schema.Union<readonly [Schema.StructWithRest<Schema.Struct<{
+    readonly overlay: Schema.String;
+    readonly info: Schema.StructWithRest<Schema.Struct<{
+        readonly title: Schema.String;
+        readonly version: Schema.String;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+    readonly extends: Schema.optionalKey<Schema.String>;
+    readonly actions: Schema.$Array<Schema.StructWithRest<Schema.Struct<{
+        readonly target: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+        readonly update: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.Finite, Schema.Null]>>;
+        readonly remove: Schema.optionalKey<Schema.Boolean>;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>, Schema.StructWithRest<Schema.Struct<{
+    readonly overlay: Schema.String;
+    readonly info: Schema.StructWithRest<Schema.Struct<{
+        readonly title: Schema.String;
+        readonly version: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+    readonly extends: Schema.optionalKey<Schema.String>;
+    readonly actions: Schema.$Array<Schema.StructWithRest<Schema.Struct<{
+        readonly target: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+        readonly update: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.Finite, Schema.Null]>>;
+        readonly copy: Schema.optionalKey<Schema.String>;
+        readonly remove: Schema.optionalKey<Schema.Boolean>;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>]>;
+export type Overlay = typeof Overlay.Type;

package/dist/schemas.js

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+import * as V10 from "./schemas/1.0.js";
+import * as V11 from "./schemas/1.1.js";
+export const OverlayInfo = Schema.Union([V10.OverlayInfo, V11.OverlayInfo]);
+export const OverlayAction = Schema.Union([V10.OverlayAction, V11.OverlayAction]);
+export const Overlay = Schema.Union([V10.Overlay, V11.Overlay]);

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@shipworthy/openapi-overlay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@shipworthy/openapi-parser": "1.0.0",
+    "effect": "4.1.4",
+    "jsonpath-rfc9535": "1.3.0"
+  },
+  "description": "Apply versioned OpenAPI Overlay documents with Effect.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipWorthyAI/openapi.git",
+    "directory": "packages/openapi-overlay"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schemas/1.0": {
+      "types": "./dist/schemas/1.0.d.ts",
+      "default": "./dist/schemas/1.0.js"
+    },
+    "./schemas/1.1": {
+      "types": "./dist/schemas/1.1.d.ts",
+      "default": "./dist/schemas/1.1.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "generate:schemas": "bun scripts/generate-schemas.ts",
+    "check:schemas": "bun scripts/generate-schemas.ts --check",
+    "test": "vitest run",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.1.4",
+    "@effect/vitest": "4.1.4",
+    "@shipworthy/typescript-config": "0.0.1",
+    "@types/node": "^26.6.6",
+    "oxfmt": "^0.78.0",
+    "typescript": "^7.0.2",
+    "vitest": "5.1.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}