001/*
002 * Copyright 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet;
018
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import javax.annotation.concurrent.ThreadSafe;
023
024import static java.util.Objects.requireNonNull;
025
026/**
027 * Immutable schema compiled under Soklet MCP Tool Schema Profile 1.
028 *
029 * <p>Instances expose derived, fixed, and application-authored input schemas
030 * for inspection, but applications cannot construct or replace this type
031 * directly. Programmatic tool registrations may provide an authored Profile 1
032 * object-root input document through
033 * {@link McpToolRegistration.ArgumentTypeStage#inputSchema(McpJsonObject)};
034 * output schemas remain derived. Profile 1 is a closed generation and
035 * validation profile based on JSON Schema Draft 2020-12, not a complete Draft
036 * 2020-12 implementation.</p>
037 *
038 * <p>Evaluation has independent resource bounds, including one million
039 * operations and 128 active evaluation calls. A value within the JSON byte,
040 * depth and node limits can still exhaust schema evaluation. Repeated
041 * applicators, reference traversals, equality checks and object-member sorting
042 * contribute work; satisfying the schema semantically does not guarantee
043 * completion within these bounds. Limit exhaustion rejects input through the
044 * revision's ordinary tool-validation result, and output through the fixed
045 * internal-error result. Internal diagnostics are not exposed on the wire.</p>
046 *
047 * @author <a href="https://www.revetkn.com">Mark Allen</a>
048 */
049@ThreadSafe
050public final class McpToolSchema {
051        @NonNull
052        private final McpJsonObject document;
053
054        McpToolSchema(@NonNull McpJsonObject document) {
055                this.document = requireNonNull(document);
056        }
057
058        /**
059         * Returns the preserved schema document published on the MCP wire.
060         *
061         * @return immutable schema object
062         */
063        @NonNull
064        public McpJsonObject getDocument() {
065                return this.document;
066        }
067
068        /** @return whether the schema documents are structurally equal */
069        @Override
070        public boolean equals(@Nullable Object other) {
071                return this == other
072                                || other instanceof McpToolSchema schema
073                                && this.document.equals(schema.document);
074        }
075
076        /** @return structural schema-document hash code */
077        @Override
078        public int hashCode() {
079                return this.document.hashCode();
080        }
081}