@simtlix/simfinity-descriptor 0.0.0-stage → 3.15.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @simtlix/simfinity-descriptor
 
-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.
+Optional schema-owned JSON client metadata for Simfinity. Depends on the exact
+matching version of `@simtlix/simfinity-core`; supports both database facades.
+Available since 3.15.0. Install it
+as a direct application dependency at the version of your Simfinity runtime.
+
+```javascript
+import { buildClientDescriptor, createClientDescriptorHandler } from '@simtlix/simfinity-descriptor';
+const descriptor = buildClientDescriptor(schema);
+app.all('/graphql-metadata', createClientDescriptorHandler(schema, { authorize: 'public' }));
+```
+
+The application supplies its exact `createSchema()` result and explicitly chooses
+public access or an authorization function. Importing this package does not patch
+GraphQL introspection. See the [client descriptor guide](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html)
+for gated access, root input hints, early opt-out and client migration limits.
+
+`rootInputUsage` reports whether a field is required or optional in the actual
+generated root add/update input. Nested collection inputs can omit the inverse
+reference supplied by their parent. Descriptors do not serialize arbitrary
+validators or determine dynamic permissions. Finish declarations before the first
+build; create a new schema and handler for metadata changes. Clones and composed
+schemas do not inherit ownership.
+
+Core remains dependency-free; structural HTTP declarations need no Node ambient
+types. Directly importing `@simtlix/simfinity-core/introspection` requires core as
+a direct dependency pinned to the facade's version. The 3.x introspection default
+remains enabled, and clients selecting `__Field.extensions` must migrate before
+using the early opt-out.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@simtlix/simfinity-descriptor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.15.0",
+  "description": "Schema-owned client metadata and an explicitly authorized HTTP endpoint for Simfinity",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/simtlix/simfinity.js",
+    "directory": "packages/descriptor"
+  },
+  "dependencies": {
+    "@simtlix/simfinity-core": "3.15.0"
+  },
+  "peerDependencies": {
+    "graphql": "^16.11.0"
+  },
+  "keywords": [
+    "simfinity",
+    "graphql",
+    "metadata",
+    "descriptor"
+  ]
+}

package/src/client-descriptor.js

@@ -0,0 +1,212 @@
+import {
+  astFromValue, getNamedType, isEnumType, isInputObjectType, isInterfaceType, isNonNullType,
+  isObjectType, isScalarType, isUnionType, print,
+} from 'graphql';
+import SimfinityError from '@simtlix/simfinity-core/internal/errors';
+import { schemaRegistrations } from '@simtlix/simfinity-core/internal/schema-registrations';
+import { getFieldStorageName, getListShape, isVirtualField, normalizeConnectionField, virtualFieldOptions } from '@simtlix/simfinity-core/internal/relation-storage';
+import { packageInfo } from './package-info.js';
+
+// Exact schema ownership. No global adoption or field-name inference across module instances.
+const snapshots = new WeakMap();
+const textOrNull = (value) => (typeof value === 'string' ? value : null);
+const descriptionOf = (value) => ({ description: textOrNull(value.description) });
+const deprecated = (value) => (value.deprecationReason == null ? {} : { deprecationReason: textOrNull(value.deprecationReason) });
+const mapOf = (entries) => Object.fromEntries(entries);
+const sortedMap = (entries) => mapOf([...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+const freeze = (value) => {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.values(value).forEach(freeze);
+    Object.freeze(value);
+  }
+  return value;
+};
+
+const scalarBase = (type) => {
+  if (!type.baseScalarType) return null;
+  const seen = new Set([type]);
+  let base = type.baseScalarType;
+  while (base && !seen.has(base)) {
+    seen.add(base);
+    if (!base.baseScalarType) return textOrNull(base.name);
+    base = base.baseScalarType;
+  }
+  return null;
+};
+
+const collectTypes = (schema) => {
+  const found = new Map();
+  const pending = [schema.getQueryType(), schema.getMutationType()];
+  while (pending.length) {
+    const type = getNamedType(pending.pop());
+    if (!type || found.has(type.name)) continue;
+    found.set(type.name, type);
+    if (isUnionType(type)) pending.push(...type.getTypes());
+    if (isInterfaceType(type)) pending.push(...schema.getPossibleTypes(type));
+    if (isObjectType(type) || isInterfaceType(type)) pending.push(...type.getInterfaces());
+    if (isObjectType(type) || isInterfaceType(type) || isInputObjectType(type)) {
+      for (const field of Object.values(type.getFields())) {
+        pending.push(field.type, ...(field.args || []).map((arg) => arg.type));
+      }
+    }
+  }
+  return found;
+};
+
+// A collection can name the child's GraphQL member or its stored alias. Never invent a private link.
+const inverseOfCollection = (child, connectionField) => {
+  if (!isObjectType(child) || !connectionField) return null;
+  const normalized = normalizeConnectionField(child, connectionField).graphqlFieldName;
+  const matches = Object.entries(child.getFields()).filter(([name, field]) => (
+    name === connectionField || getFieldStorageName(name, field) === connectionField
+  ));
+  return matches.length === 1 ? normalized : null;
+};
+const relationOf = (owner, field) => {
+  const relation = field.extensions?.relation;
+  const target = getNamedType(field.type);
+  if (!relation || !isObjectType(target)) return null;
+  const collection = getListShape(field.type);
+  let inverseField = null;
+  if (!relation.embedded) {
+    if (collection) inverseField = inverseOfCollection(target, relation.connectionField);
+    else {
+      const matches = Object.entries(target.getFields()).filter(([, candidate]) => (
+        !candidate.extensions?.relation?.embedded && candidate.extensions?.relation
+        && getListShape(candidate.type)?.itemType === owner
+        && inverseOfCollection(owner, candidate.extensions.relation.connectionField) === field.name
+      ));
+      if (matches.length === 1) [inverseField] = matches[0];
+    }
+  }
+  return {
+    target: target.name, embedded: !!relation.embedded,
+    connectionField: textOrNull(relation.connectionField), displayField: textOrNull(relation.displayField), inverseField,
+  };
+};
+const fieldKind = (field, relation) => {
+  const named = getNamedType(field.type);
+  if (relation) return relation.embedded ? 'embedded' : getListShape(field.type) ? 'collection' : 'reference';
+  if (isScalarType(named)) return 'scalar';
+  if (isEnumType(named)) return 'enum';
+  if (isInterfaceType(named)) return 'interface';
+  if (isUnionType(named)) return 'union';
+  return 'object';
+};
+
+const createDescriptor = (schema, registrations) => {
+  const types = collectTypes(schema);
+  const registered = new Map(registrations.map((entry) => [entry.gqltype, entry]));
+  const defaults = [];
+  const inputValues = new Map();
+  const input = (field) => {
+    if (inputValues.has(field)) return inputValues.get(field);
+    const result = { name: field.name, type: String(field.type), ...descriptionOf(field), ...deprecated(field), hasDefault: field.defaultValue !== undefined };
+    // Do not invoke application scalar serializers during createSchema(). Keep these references only
+    // until the first explicit descriptor build, then release them. Nothing executable enters JSON.
+    inputValues.set(field, result);
+    if (result.hasDefault) defaults.push({ target: result, type: field.type, value: field.defaultValue });
+    return result;
+  };
+  const operation = (field) => ({ args: field.args.map(input), returns: String(field.type), ...descriptionOf(field), ...deprecated(field) });
+  const queryEntries = Object.entries(schema.getQueryType()?.getFields() || {}).map(([name, field]) => {
+    const registration = registrations.find((entry) => entry.endpoint
+      && entry.simpleEntityEndpointName === name && field.type === entry.gqltype);
+    const marker = field.extensions?.simfinityQuery;
+    const kind = registration ? 'get' : marker?.operation === 'find' ? 'list' : marker?.operation === 'aggregate' ? 'aggregate' : 'customQuery';
+    return [name, { ...operation(field), type: registration?.gqltype.name || (kind !== 'customQuery' ? marker.typeName : null), operation: kind,
+      ...(marker?.view ? { view: marker.view.name } : {}) }];
+  });
+  const mutationKinds = { save: 'add', update: 'update', delete: 'delete', state_changed: 'transition', custom_mutation: 'customMutation' };
+  const mutationEntries = Object.entries(schema.getMutationType()?.getFields() || {}).map(([name, field]) => {
+    const marker = field.extensions?.simfinityMutation;
+    const kind = mutationKinds[marker?.operation] || 'customMutation';
+    const result = { ...operation(field), type: marker?.typeName || null, operation: kind };
+    if (['add', 'update', 'delete'].includes(kind) && result.description === kind) result.description = null;
+    if (kind === 'transition') Object.assign(result, { action: marker.action, from: textOrNull(marker.from), to: textOrNull(marker.to) });
+    return [name, result];
+  });
+  const operations = { query: sortedMap(queryEntries), mutation: sortedMap(mutationEntries) };
+  const typeEntries = [...types].map(([name, type]) => {
+    const entry = registered.get(type);
+    let kind = 'object';
+    if (isInputObjectType(type)) kind = 'input';
+    else if (isScalarType(type)) kind = 'scalar';
+    else if (isEnumType(type)) kind = 'enum';
+    else if (isInterfaceType(type)) kind = 'interface';
+    else if (isUnionType(type)) kind = 'union';
+    const associated = [...queryEntries, ...mutationEntries].filter(([, op]) => op.type === name);
+    if (entry?.endpoint && associated.length) kind = 'entity';
+    const result = { kind, ...descriptionOf(type) };
+    if (kind === 'entity') {
+      result.endpoints = mapOf(associated.filter(([, op]) => !op.view && ['get', 'list', 'aggregate', 'add', 'update', 'delete'].includes(op.operation)).map(([key, op]) => [op.operation, key]));
+    }
+    const rootInputs = ['add', 'update'].flatMap((operation) => {
+      const endpoint = result.endpoints?.[operation];
+      const root = endpoint && schema.getMutationType().getFields()[endpoint];
+      const inputType = root && getNamedType(root.args.find((arg) => arg.name === 'input')?.type);
+      return isInputObjectType(inputType) ? [[operation, inputType.getFields()]] : [];
+    });
+    if (entry) {
+      const inputs = Object.entries({ add: entry.inputType, update: entry.updateInputType })
+        .filter(([, item]) => item && types.get(item.name) === item).map(([key, item]) => [key, item.name]);
+      if (inputs.length) result.inputs = mapOf(inputs);
+      if (kind === 'entity') {
+        const state = type.getFields().state;
+        const enumType = state && getNamedType(state.type);
+        result.stateMachine = entry.stateMachine && isEnumType(enumType) ? {
+          field: 'state', enum: enumType.name, initialState: textOrNull(entry.stateMachine.initialState?.name),
+          states: enumType.getValues().map((value) => value.name),
+          actions: mutationEntries.filter(([, op]) => op.type === name && op.operation === 'transition').map(([mutation, op]) => ({ name: op.action, mutation, description: op.description, from: op.from, to: op.to })),
+        } : null;
+      }
+    }
+    if (isInputObjectType(type)) result.fields = Object.values(type.getFields()).map(input);
+    else if (isObjectType(type) || isInterfaceType(type)) {
+      result.interfaces = type.getInterfaces().map((item) => item.name);
+      result.fields = Object.values(type.getFields()).map((field) => {
+        const relation = relationOf(type, field);
+        const virtual = virtualFieldOptions(field);
+        return {
+          name: field.name, type: String(field.type), kind: fieldKind(field, relation), ...descriptionOf(field), ...deprecated(field),
+          readOnly: !!field.extensions?.readOnly || !!virtual, unique: field.extensions?.unique === true,
+          stateMachine: !!entry?.stateMachine && field.name === 'state' && !field.extensions?.readOnly,
+          ...(relation ? { relation } : {}), ...(virtual ? { virtual } : {}),
+          ...(entry ? { queryable: !isVirtualField(field) && entry.queryableFields[field.name] } : {}),
+          ...(rootInputs.length ? { rootInputUsage: mapOf(rootInputs.flatMap(([operation, fields]) => {
+            const inputField = fields[field.name];
+            return inputField ? [[operation, isNonNullType(inputField.type) && inputField.defaultValue === undefined ? 'required' : 'optional']] : [];
+          })) } : {}),
+          ...(field.args.length ? { args: field.args.map(input) } : {}),
+        };
+      });
+    }
+    if (isInterfaceType(type)) result.possibleTypes = schema.getPossibleTypes(type).map((item) => item.name);
+    if (isUnionType(type)) result.possibleTypes = type.getTypes().map((item) => item.name);
+    if (isEnumType(type)) result.values = type.getValues().map((item) => ({ name: item.name, ...descriptionOf(item), deprecationReason: textOrNull(item.deprecationReason) }));
+    if (isScalarType(type)) result.baseScalar = scalarBase(type);
+    return [name, result];
+  });
+  snapshots.set(schema, { document: { formatVersion: 1, generator: packageInfo,
+    roots: { query: schema.getQueryType()?.name || null, mutation: schema.getMutationType()?.name || null },
+    operations, types: sortedMap(typeEntries) }, defaults });
+};
+
+export const buildClientDescriptor = (schema) => {
+  const registrations = schemaRegistrations(schema);
+  if (!registrations) throw new SimfinityError('Expected a Simfinity schema returned by this core installation', 'NOT_A_SIMFINITY_SCHEMA', 500);
+  if (!snapshots.has(schema)) createDescriptor(schema, registrations);
+  const snapshot = snapshots.get(schema);
+  if (snapshot.defaults) {
+    const pending = snapshot.defaults;
+    snapshot.defaults = null;
+    for (const { target, type, value } of pending) {
+      try {
+        const ast = astFromValue(value, type);
+        if (ast) target.defaultValue = print(ast);
+      } catch { /* Opaque custom scalar defaults are deliberately omitted. */ }
+    }
+    freeze(snapshot.document);
+  }
+  return snapshot.document;
+};

package/src/http.js

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { buildClientDescriptor } from './client-descriptor.js';
+import SimfinityError from '@simtlix/simfinity-core/internal/errors';
+
+const canonical = (value) => {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+};
+const invalid = () => new SimfinityError('Invalid client descriptor handler options: provide authorize: public or a function, and optional context/onError', 'INVALID_CLIENT_DESCRIPTOR_OPTIONS', 500);
+const KEYS = new Set(['authorize', 'context', 'onError']);
+const readOptions = (options) => {
+  if (!options || ![Object.prototype, null].includes(Object.getPrototypeOf(options))
+    || Reflect.ownKeys(options).some((key) => !KEYS.has(key))
+    || !Object.hasOwn(options, 'authorize')
+    || (options.authorize !== 'public' && typeof options.authorize !== 'function')
+    || (options.onError !== undefined && typeof options.onError !== 'function')) throw invalid();
+  return { authorize: options.authorize, context: options.context, onError: options.onError };
+};
+// Validate the whole list, including quoted commas; an arbitrary substring is not a cache match.
+const matches = (header, etag) => {
+  if (typeof header !== 'string') return false;
+  const value = header.trim();
+  if (value === '*') return true;
+  if (!/^(?:W\/)?"[\x21\x23-\x7e\x80-\xff]*"(?:\s*,\s*(?:W\/)?"[\x21\x23-\x7e\x80-\xff]*")*$/.test(value)) return false;
+  return [...value.matchAll(/(?:W\/)?"[\x21\x23-\x7e\x80-\xff]*"/g)].some(([tag]) => tag.replace(/^W\//, '') === etag);
+};
+const envelope = (message, code) => JSON.stringify({ errors: [{ message, extensions: { code } }] });
+
+/** A separately mounted, immutable descriptor. Authorization runs on HEAD and cache hits too. */
+export const createClientDescriptorHandler = (schema, options) => {
+  const { authorize, context, onError } = readOptions(options);
+  const body = JSON.stringify(canonical(buildClientDescriptor(schema)));
+  const etag = `"${createHash('sha256').update(body).digest('hex')}"`;
+  const gated = authorize !== 'public';
+  return async (req, res) => {
+    const send = (status, content) => {
+      res.statusCode = status;
+      res.setHeader('Content-Type', 'application/json; charset=utf-8');
+      res.end(req.method === 'HEAD' ? undefined : content);
+    };
+    try {
+      if (!['GET', 'HEAD'].includes(req.method)) {
+        res.setHeader('Allow', 'GET, HEAD');
+        res.setHeader('Cache-Control', 'no-store');
+        send(405, envelope('Method not allowed', 'METHOD_NOT_ALLOWED'));
+        return;
+      }
+      const ctx = typeof context === 'function' ? await context(req) : context;
+      if (gated) {
+        const allowed = await authorize(req, ctx);
+        if (allowed !== true && allowed !== undefined) throw new SimfinityError('Access denied', 'FORBIDDEN', 403);
+      }
+      res.setHeader('Cache-Control', gated ? 'private, no-cache' : 'no-cache');
+      if (gated) res.setHeader('Vary', 'Authorization, Cookie');
+      res.setHeader('ETag', etag);
+      if (matches(req.headers['if-none-match'], etag)) {
+        res.statusCode = 304;
+        res.end();
+      } else send(200, body);
+    } catch (error) {
+      const known = error instanceof SimfinityError && [401, 403].includes(error.getStatus());
+      try { if (!known && onError) await onError(error, req, res); } catch { /* Reporting cannot replace the HTTP result. */ }
+      if (res.headersSent || res.writableEnded || res.destroyed) return;
+      res.removeHeader('ETag');
+      res.setHeader('Cache-Control', 'no-store');
+      send(known ? error.getStatus() : 500,
+        envelope(known ? error.message : 'Internal server error', known ? error.getCode() : 'INTERNAL_SERVER_ERROR'));
+    }
+  };
+};

package/src/index.js

@@ -0,0 +1,2 @@
+export { buildClientDescriptor } from './client-descriptor.js';
+export { createClientDescriptorHandler } from './http.js';

package/src/package-info.js

@@ -0,0 +1,2 @@
+// Generated by scripts/release-packages.js; keeps the descriptor builder free of Node/JSON loader dependencies.
+export const packageInfo = Object.freeze({ name: '@simtlix/simfinity-descriptor', version: '3.15.0' });

package/types/index.d.ts

@@ -0,0 +1,96 @@
+import type { GraphQLSchema } from 'graphql';
+
+export interface ClientDescriptorInputValue {
+  readonly name: string;
+  readonly type: string;
+  readonly description: string | null;
+  readonly deprecationReason?: string | null;
+  readonly hasDefault: boolean;
+  /** External GraphQL literal; omitted for unrepresentable custom defaults. */
+  readonly defaultValue?: string;
+}
+export interface ClientDescriptorRelation {
+  readonly target: string;
+  readonly embedded: boolean;
+  readonly connectionField: string | null;
+  readonly displayField: string | null;
+  readonly inverseField: string | null;
+}
+export interface ClientDescriptorField {
+  readonly name: string;
+  readonly type: string;
+  readonly kind: 'scalar' | 'enum' | 'embedded' | 'reference' | 'collection' | 'object' | 'interface' | 'union';
+  readonly description: string | null;
+  readonly deprecationReason?: string | null;
+  readonly readOnly: boolean;
+  readonly unique: boolean;
+  readonly stateMachine: boolean;
+  readonly queryable?: boolean;
+  /** Usage in this schema's generated root add/update inputs, not permissions or nested inputs. */
+  readonly rootInputUsage?: Readonly<{ add?: 'required' | 'optional'; update?: 'required' | 'optional' }>;
+  readonly virtual?: Readonly<{ mcp: 'tool' | 'select' | false }>;
+  readonly relation?: ClientDescriptorRelation;
+  readonly args?: readonly ClientDescriptorInputValue[];
+}
+export interface ClientDescriptorOperation {
+  readonly type: string | null;
+  readonly operation: 'get' | 'list' | 'aggregate' | 'add' | 'update' | 'delete' | 'transition' | 'customQuery' | 'customMutation';
+  readonly args: readonly ClientDescriptorInputValue[];
+  readonly returns: string;
+  readonly description: string | null;
+  readonly deprecationReason?: string | null;
+  readonly view?: string;
+  readonly action?: string;
+  readonly from?: string | null;
+  readonly to?: string | null;
+}
+export interface ClientDescriptorStateMachine {
+  readonly field: 'state';
+  readonly enum: string;
+  readonly initialState: string | null;
+  readonly states: readonly string[];
+  readonly actions: readonly Readonly<{ name: string; mutation: string; description: string | null; from: string | null; to: string | null }>[];
+}
+export interface ClientDescriptorType {
+  readonly kind: 'entity' | 'object' | 'interface' | 'union' | 'input' | 'enum' | 'scalar';
+  readonly description: string | null;
+  readonly endpoints?: Readonly<Partial<Record<'get' | 'list' | 'aggregate' | 'add' | 'update' | 'delete', string>>>;
+  readonly inputs?: Readonly<{ add?: string; update?: string }>;
+  readonly stateMachine?: ClientDescriptorStateMachine | null;
+  readonly fields?: readonly (ClientDescriptorField | ClientDescriptorInputValue)[];
+  readonly interfaces?: readonly string[];
+  readonly possibleTypes?: readonly string[];
+  readonly values?: readonly Readonly<{ name: string; description: string | null; deprecationReason: string | null }>[];
+  readonly baseScalar?: string | null;
+}
+export interface ClientDescriptor {
+  readonly formatVersion: 1;
+  readonly generator: Readonly<{ name: '@simtlix/simfinity-descriptor'; version: string }>;
+  readonly roots: Readonly<{ query: string | null; mutation: string | null }>;
+  readonly types: Readonly<Record<string, ClientDescriptorType>>;
+  readonly operations: Readonly<{ query: Readonly<Record<string, ClientDescriptorOperation>>; mutation: Readonly<Record<string, ClientDescriptorOperation>> }>;
+}
+/** Immutable metadata of this exact createSchema result; rejects transformed/foreign schemas. */
+export function buildClientDescriptor(schema: GraphQLSchema): ClientDescriptor;
+
+/** Minimal structural Node/Express request; no Node ambient types are required. */
+export interface DescriptorRequest {
+  method?: string | undefined;
+  headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+}
+export interface DescriptorResponse {
+  statusCode: number;
+  readonly headersSent?: boolean;
+  readonly writableEnded?: boolean;
+  readonly destroyed?: boolean;
+  setHeader(name: string, value: string): unknown;
+  removeHeader(name: string): void;
+  end(body?: string): unknown;
+}
+export interface ClientDescriptorHandlerOptions<Context = unknown> {
+  authorize: 'public' | ((req: DescriptorRequest, context: Context) => boolean | void | Promise<boolean | void>);
+  context?: Context | ((req: DescriptorRequest) => Context | Promise<Context>);
+  /** Reports unexpected failures, not expected 401/403 denials. */
+  onError?: (error: unknown, req: DescriptorRequest, res: DescriptorResponse) => void | Promise<void>;
+}
+export function createClientDescriptorHandler<Context = unknown>(schema: GraphQLSchema, options: ClientDescriptorHandlerOptions<Context>): (req: DescriptorRequest, res: DescriptorResponse) => Promise<void>;