@starci/hfs 4.7.32 → 4.7.34

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.7.34 - 2026-10-26
+- Fixed: `starci app db restamp` considers only active migrations when validating names and choosing unoccupied versions. Legacy archive names no longer block preview or apply, and archived files stay untouched.
+- Changed: the loosening check reads the tree as it stands and never its history. The bundled `scripts/lib/loosening-state.mjs` (with `js-lex.mjs` and `loosening-config.mjs`) replaces the diff detector; `HFS_BYPASS_MARKER` (R303) reads it: a suppression word opens a comment, a test marker stands in code, a swallowed failure stands in a shell line or in the string a script hands a shell, a package.json is judged by its scripts, and the same words quoted as data are no bypass. It also refuses a coverage target or threshold below the canon, a relaxing switch, a disabled ESLint rule, a tsconfig strictness option turned off and an exception file that `knowledge/hfs/design-truths.yaml` does not list. `--passWithNoTests`, `--coverageThreshold`, `--no-error-on-unmatched-pattern` and a `--max-warnings` budget are bypasses in a script, a hook or a workflow.
+- Added: `starci app emit` carries class-validator `MaxLength`, `ArrayMaxSize`, `Min` and `Max` of GraphQL input types and REST operation DTOs into the contract (a GraphQL `@inputBounds` directive and an OpenAPI constraint), and the `@starci/hfs/form-bounds` codegen plugin turns them into typed `INPUT_BOUNDS` and `inputBoundsIssues` for the form canon. The app codegen template refuses legacy or unsupported bounds metadata.
+- Changed: the operation emit refuses a non-strict `z.object` (open on the wire), publishes the real maximum length of fixed-format strings (`z.uuid()`, `z.ipv4()` and kin) and keeps `readOnly` out of request schemas.
+- Changed: operation tables declare runtime input/output schemas from owner-local `*.schema.ts` exports. `starci app emit` derives OpenAPI 3.1 with the app's `z.toJSONSchema`, preserving bounds and defaults, refusing open or unrepresentable wire values, and evaluating only schema modules. Package specs cover conversion, isolated worker execution and rejection paths.
+
+## 4.7.33 - 2026-10-25
+- Changed: the bundled canon pins select @starci/stylelint-canon 2.0.11, @starci/cli 1.7.33 and the canons 3.4.41 and 8.4.40.
+
 ## 4.7.32 - 2026-10-25
 - Changed: the bundled canon pins select @starci/grammar 0.11.0, @starci/cli 1.7.32 and the canons 3.4.40 and 8.4.39.
 

package/README.md

@@ -12,8 +12,8 @@ starci app scaffold <name> [--into <dir>] [--edition full|lite] [--cwd <dir>]
 starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [--fe] [--no-types] [options] [--cwd <dir>]
 starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--format text|json] [--sonar <file>]
 starci app sync (--check | --write) [--cwd <dir>]
-starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--edition full] [--db-types]
-starci app upgrade [--edition full] [--plan]
+starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--db-types]
+starci app upgrade [--plan]
 starci app stack <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--cwd <dir>]
 starci app explain <path> [--cwd <dir>] [--json]
 starci app emit [--cwd <dir>]
@@ -56,10 +56,17 @@ The lite additions are deliberately narrow:
 `starci app emit` continues to emit the enabled back-end snapshots and also writes `supabase/types/database.types.ts` when
 the `app.supabase.types` slot is enabled. The local Supabase stack must be running for generation.
 
-Plan the transition with `starci app upgrade --edition full --plan`, then use `starci app check --edition full [--db-types]` to judge the
-unchanged lite tree through the full-edition view. The check is read-only; `--db-types` includes a fresh generated-types
-comparison when the local stack is available. Applying `starci app upgrade --edition full` adds the full-only managed configuration,
-test layers and cli requirements without rewriting product code. Downgrade to lite is not supported.
+Input bounds stay with the backend DTO: `MaxLength`, `ArrayMaxSize`, `Min` and `Max` become GraphQL `@inputBounds`
+input-field directives or JSON Schema constraints on the REST operation table's DTO properties. Codegen derives
+`INPUT_BOUNDS` beside GraphQL wire types and `REST_INPUT_BOUNDS` under the REST API owner's `__generated__/` directory.
+Each generated module also exports `inputBoundsIssues`. Forms consume the reader and their input's bounds through the API
+owner and call it from each input object's zod `superRefine`, converting every returned field path into a translated custom issue.
+Nested input schemas compose their own refinement. The reader
+applies changed and newly added bounds automatically; required fields, types and formats remain in zod. Conflicting GraphQL
+bounds across services and undecidable backend bounds refuse generation; snapshot checks detect changed limits.
+Emit contracts with matching HFS and CLI versions before codegen; legacy or unsupported bounds metadata refuses generation.
+
+The edition is chosen once at scaffold: a lite app stays lite and a full app stays full, and `starci app upgrade` refuses a lite app (`HFS_UPGRADE_EDITION_FIXED`). `starci app check --edition <edition>` accepts only the edition `hfs.json` declares.
 
 A new full app ships its test world (`scaffold/test-world.mjs`): the `@starci/test-world` declaration under `be/src/tests/world/`
 (the dev stack's Postgres per connection, the api apps, the cli app's migration runner as the migrate step), an integration spec of

package/emit/contracts.mjs

@@ -2,10 +2,11 @@
  * `starci app emit`: writes `contracts/<service>/events.json` for every service that declares typed event classes under
  * `src/modules/events/<service>/` (events.mjs: the async contract, R166), `contracts/<app>/schema.graphql` for every api app of hfs.json that serves GraphQL, and
  * `contracts/<app>/openapi.json` for every api app whose `apps/<app>/src/operations.ts` exports the typed operation table
- * `OPERATIONS` (operations.mjs: OpenAPI 3.1 read from the TypeScript checker; nothing is executed).
+ * `OPERATIONS` (operations.mjs: OpenAPI 3.1 derived from zod schema modules, with closed refusal codes proved by the checker).
  *
- * The snapshot is `printSchema(lexicographicSortSchema(schema))`, nothing else, so it is deterministic and never carries a
- * generator banner. It needs no environment, no database and no network, and never boots the app.
+ * The GraphQL snapshot prints the lexicographically sorted schema with class-validator bounds on input fields as
+ * `@inputBounds` directives. OpenAPI carries the equivalent JSON Schema property and item constraints. It needs no
+ * environment, no database and no network, and never boots the app.
  *
  * What an app serves is decided from its source (`static-graph.mjs`): the module graph is walked from `AppModule` of
  * `apps/<app>/src/app.module.ts` through every import (imports of imports, `register`/`forRoot`/`forRootAsync` dynamic modules,

package/emit/form-bounds-reader.ts.partial

@@ -0,0 +1,58 @@
+/** A form constraint failure; the form supplies translated copy for its field. */
+export type InputBoundIssue = {
+    readonly path: readonly (string | number)[]
+    readonly kind: "maxLength" | "maxItems" | "min" | "max"
+    readonly bound: number
+}
+
+/** Checks limits only; the form's zod schema owns required values, types and formats. */
+const fieldBoundIssues = (
+    value: unknown,
+    limits: InputBoundField,
+    path: readonly (string | number)[],
+): InputBoundIssue[] => {
+    const issues: InputBoundIssue[] = []
+    if (typeof value === "string" && limits.maxLength !== undefined && value.length > limits.maxLength) {
+        issues.push({ path, kind: "maxLength", bound: limits.maxLength })
+    }
+    if (Array.isArray(value) && limits.maxItems !== undefined && value.length > limits.maxItems) {
+        issues.push({ path, kind: "maxItems", bound: limits.maxItems })
+    }
+    if (typeof value === "number") {
+        if (limits.min !== undefined && (!Number.isFinite(value) || value < limits.min)) {
+            issues.push({ path, kind: "min", bound: limits.min })
+        }
+        if (limits.max !== undefined && (!Number.isFinite(value) || value > limits.max)) {
+            issues.push({ path, kind: "max", bound: limits.max })
+        }
+    }
+    return issues
+}
+
+/**
+ * Checks one input object's bounds from its zod superRefine callback, so newly declared limits apply automatically.
+ * Compose nested input object schemas with their own bounds refinement; zod prefixes their relative issue paths.
+ * Missing optional values are left to zod. Maximum string length uses UTF-16 units, conservatively stricter than
+ * class-validator. Array item checks stop when the array itself exceeds its maximum size.
+ */
+export const inputBoundsIssues = (
+    bounds: Readonly<Record<string, InputBoundField>>,
+    values: Readonly<Record<string, unknown>>,
+): readonly InputBoundIssue[] => {
+    const issues: InputBoundIssue[] = []
+    for (const [field, limits] of Object.entries(bounds)) {
+        const value = values[field]
+        issues.push(...fieldBoundIssues(value, limits, [field]))
+        if (!Array.isArray(value) || (limits.maxItems !== undefined && value.length > limits.maxItems)) continue
+        const itemLimits: InputBoundField = {
+            maxLength: limits.itemMaxLength,
+            maxItems: limits.itemMaxItems,
+            min: limits.itemMin,
+            max: limits.itemMax,
+        }
+        value.forEach((item: unknown, index: number) => {
+            issues.push(...fieldBoundIssues(item, itemLimits, [field, index]))
+        })
+    }
+    return issues
+}

package/emit/form-bounds.mjs

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import { INPUT_BOUND_ARGUMENTS, INPUT_BOUNDS_DIRECTIVE, INPUT_BOUNDS_VERSION, INPUT_BOUNDS_VERSION_ARGUMENT, INPUT_BOUNDS_OPENAPI_EXTENSION, JSON_SCHEMA_BOUND_KEYS } from './input-bounds.mjs';
+import { byCodeUnit } from '../report/order.mjs';
+
+const READER = `/** One field's backend bounds, including each-item validators. */\ntype InputBoundField = Readonly<Partial<Record<${Object.keys(INPUT_BOUND_ARGUMENTS).map(key => JSON.stringify(key)).join(' | ')}, number | undefined>>>\n\n${fs.readFileSync(new URL('./form-bounds-reader.ts.partial', import.meta.url), 'utf8')}`;
+const graphqlBoundsText = inputs => `/** Backend input bounds, generated from the contract. */\nexport const INPUT_BOUNDS = ${JSON.stringify(inputs, null, 2)} as const\n\n${READER}`;
+
+/** Clears generated GraphQL form limits when the last backend schema snapshot is removed. */
+export function emptyInputBoundsSource() {
+  return graphqlBoundsText({});
+}
+
+const inputTypes = schema => Object.values(schema.getTypeMap()).filter(type => type.astNode?.kind === 'InputObjectTypeDefinition');
+
+function requireGraphqlBoundsFormat(schema, label = 'GraphQL contract') {
+  if (inputTypes(schema).length === 0) return;
+  const directive = schema.getDirective(INPUT_BOUNDS_DIRECTIVE);
+  const args = new Map((directive?.args ?? []).map(argument => [argument.name, argument]));
+  const version = args.get(INPUT_BOUNDS_VERSION_ARGUMENT);
+  const argumentsMatch = Object.entries(INPUT_BOUND_ARGUMENTS).every(([name, type]) => String(args.get(name)?.type) === type);
+  if (version?.defaultValue !== INPUT_BOUNDS_VERSION || String(version?.type) !== 'Int' ||
+      args.size !== Object.keys(INPUT_BOUND_ARGUMENTS).length + 1 || !argumentsMatch) {
+    throw new Error(`${label}: missing or unsupported input-bounds metadata; run starci app emit with matching HFS/CLI versions`);
+  }
+}
+
+function fieldBounds(type, field) {
+  const directives = field.astNode?.directives?.filter((item) => item.name.value === INPUT_BOUNDS_DIRECTIVE) ?? [];
+  if (directives.length === 0) return null;
+  const label = `${type.name}.${field.name}`;
+  if (directives.length !== 1) throw new Error(`${label}: duplicate ${INPUT_BOUNDS_DIRECTIVE} directive`);
+  const bounds = {};
+  for (const argument of directives[0].arguments ?? []) {
+    const name = argument.name.value;
+    const scalar = INPUT_BOUND_ARGUMENTS[name];
+    const value = Number(argument.value.value);
+    const numeric = argument.value.kind === 'IntValue' || argument.value.kind === 'FloatValue';
+    if (name === INPUT_BOUNDS_VERSION_ARGUMENT) {
+      if (argument.value.kind !== 'IntValue' || value !== INPUT_BOUNDS_VERSION) throw new Error(`${label}: unsupported input-bounds version`);
+      continue;
+    }
+    if (!Object.hasOwn(INPUT_BOUND_ARGUMENTS, name) || !numeric || !Number.isFinite(value) ||
+        (scalar === 'Int' && (!Number.isSafeInteger(value) || value < 0))) {
+      throw new Error(`${label}: invalid input bound ${name}`);
+    }
+    if (Object.hasOwn(bounds, name)) throw new Error(`${label}: duplicate input bound ${name}`);
+    bounds[name] = value;
+  }
+  if (Object.keys(bounds).length === 0) throw new Error(`${label}: empty ${INPUT_BOUNDS_DIRECTIVE} directive`);
+  return Object.fromEntries(Object.entries(bounds).sort(([a], [b]) => byCodeUnit(a, b)));
+}
+
+/**
+ * GraphQL Code Generator plugin: derives typed form limits from the emitted input-field directives.
+ * Generate beside the wire types and import through the API owner. Legacy or unsupported metadata refuses generation;
+ * forms apply all carried limits from their translated zod refinements without importing backend code.
+ */
+export function inputBoundsPlugin(schema) {
+  requireGraphqlBoundsFormat(schema);
+  const inputs = {};
+  for (const type of inputTypes(schema).sort((a, b) => byCodeUnit(a.name, b.name))) {
+    const fields = {};
+    for (const field of Object.values(type.getFields()).sort((a, b) => byCodeUnit(a.name, b.name))) {
+      const bounds = fieldBounds(type, field);
+      if (bounds !== null) fields[field.name] = bounds;
+    }
+    inputs[type.name] = fields;
+  }
+  return graphqlBoundsText(inputs);
+}
+
+/** Refuses differing bounds on shared input names before Codegen merges multiple service schemas. */
+export function assertCompatibleInputBounds(schemas) {
+  const seen = new Map();
+  for (const [service, schema] of Object.entries(schemas)) {
+    requireGraphqlBoundsFormat(schema, service);
+    for (const type of inputTypes(schema)) {
+      for (const field of Object.values(type.getFields())) {
+        const key = `${type.name}.${field.name}`;
+        const bounds = JSON.stringify(fieldBounds(type, field));
+        const prior = seen.get(key);
+        if (prior && prior.bounds !== bounds) throw new Error(`conflicting input bounds for ${key}: ${prior.service} and ${service}`);
+        seen.set(key, { service, bounds });
+      }
+    }
+  }
+}
+
+function mergeBounds(target, source) {
+  for (const [name, value] of Object.entries(source)) {
+    if (!Number.isFinite(value) || (INPUT_BOUND_ARGUMENTS[name] === 'Int' && (!Number.isSafeInteger(value) || value < 0))) {
+      throw new Error(`invalid OpenAPI input bound ${name}`);
+    }
+    const previous = target[name];
+    target[name] = previous === undefined ? value : name.toLowerCase().includes('min') ? Math.max(previous, value) : Math.min(previous, value);
+  }
+  return target;
+}
+
+function schemaBounds(schema, components, seen = new Set()) {
+  if (!schema || typeof schema !== 'object') throw new Error('an OpenAPI property needs a schema');
+  if (seen.has(schema)) return {};
+  const next = new Set([...seen, schema]);
+  const bounds = {};
+  if (schema.$ref) {
+    const prefix = '#/components/schemas/';
+    const name = schema.$ref.startsWith(prefix) ? schema.$ref.slice(prefix.length).replaceAll('~1', '/').replaceAll('~0', '~') : null;
+    if (name === null || !Object.hasOwn(components, name)) throw new Error(`unresolved OpenAPI input reference ${schema.$ref}`);
+    mergeBounds(bounds, schemaBounds(components[name], components, next));
+  }
+  for (const key of Object.keys(INPUT_BOUND_ARGUMENTS).filter(name => !name.startsWith('item'))) {
+    const value = schema[JSON_SCHEMA_BOUND_KEYS[key] ?? key];
+    if (value !== undefined) mergeBounds(bounds, { [key]: value });
+  }
+  for (const part of [...(schema.allOf ?? []), ...(schema.anyOf ?? []), ...(schema.oneOf ?? [])]) {
+    mergeBounds(bounds, schemaBounds(part, components, next));
+  }
+  const itemSchemas = [...(schema.prefixItems ?? []), ...(schema.items ? [schema.items] : [])];
+  if (itemSchemas.length) {
+    const items = {};
+    for (const item of itemSchemas) mergeBounds(items, schemaBounds(item, components, next));
+    for (const [name, value] of Object.entries(items)) {
+      const key = `item${name[0].toUpperCase()}${name.slice(1)}`;
+      if (Object.hasOwn(INPUT_BOUND_ARGUMENTS, key)) mergeBounds(bounds, { [key]: value });
+    }
+  }
+  return Object.fromEntries(Object.entries(bounds).sort(([a], [b]) => byCodeUnit(a, b)));
+}
+
+/**
+ * Generates REST_INPUT_BOUNDS from emitted OpenAPI contracts, keyed by service, DTO and property.
+ * REST-only forms use the API owner's generated module. Union constraints are conservatively intersected;
+ * unresolved references and malformed limits refuse generation rather than retaining stale client limits.
+ */
+export function openApiBoundsSource(contracts) {
+  const services = {};
+  for (const [service, document] of Object.entries(contracts).sort(([a], [b]) => byCodeUnit(a, b))) {
+    if (document.openapi !== '3.1.0' || !document.components?.schemas) throw new Error(`${service}: expected an emitted OpenAPI 3.1 contract`);
+    if (document[INPUT_BOUNDS_OPENAPI_EXTENSION] !== INPUT_BOUNDS_VERSION) {
+      throw new Error(`${service}: missing or unsupported input-bounds metadata; run starci app emit with matching HFS/CLI versions`);
+    }
+    const inputs = {};
+    const components = document.components.schemas;
+    for (const [name, schema] of Object.entries(components).sort(([a], [b]) => byCodeUnit(a, b))) {
+      const fields = {};
+      for (const [property, definition] of Object.entries(schema.properties ?? {}).sort(([a], [b]) => byCodeUnit(a, b))) {
+        const bounds = schemaBounds(definition, components);
+        if (Object.keys(bounds).length) fields[property] = bounds;
+      }
+      if (schema.type === 'object' || schema.properties) inputs[name] = fields;
+    }
+    if (Object.keys(inputs).length) services[service] = inputs;
+  }
+  return `/** Backend input bounds, generated from OpenAPI contracts. */\nexport const REST_INPUT_BOUNDS = ${JSON.stringify(services, null, 2)} as const\n\n${READER}`;
+}

package/emit/graphql-input-bounds.mjs

@@ -0,0 +1,97 @@
+/** Adds backend class-validator input bounds to the emitted GraphQL contract. */
+import { boundsOf, INPUT_BOUND_ARGUMENTS, INPUT_BOUNDS_DIRECTIVE, INPUT_BOUNDS_VERSION, INPUT_BOUNDS_VERSION_ARGUMENT, validateBoundType } from './input-bounds.mjs';
+
+const ARGUMENTS = Object.keys(INPUT_BOUND_ARGUMENTS);
+
+function graphqlShape(type) {
+  const written = String(type);
+  if (written.endsWith('!')) return graphqlShape(type.ofType);
+  if (written.startsWith('[')) return { type: 'array', items: graphqlShape(type.ofType) };
+  if (type.name === 'Int' || type.name === 'Float') return { type: 'number' };
+  if (type.name === 'String' || type.name === 'ID' || type.getValues) return { type: 'string' };
+  return { type: null };
+}
+
+/** A bound must constrain the field or the exact collection-item type class-validator receives. */
+function validateFieldBounds(type, bounds, where) {
+  const shape = graphqlShape(type);
+  for (const key of Object.keys(bounds)) {
+    const each = key.startsWith('item');
+    if (each && !shape.items) throw new Error(`${where}: each:true bounds require an array`);
+    const plainKey = each ? `${key[4].toLowerCase()}${key.slice(5)}` : key;
+    validateBoundType((each ? shape.items : shape).type, plainKey, where);
+  }
+}
+
+function inputFields(inputs, input) {
+  const fields = new Map();
+  let target = input.target;
+  while (target && target !== Function.prototype) {
+    for (const property of inputs.get(target)?.properties ?? []) {
+      if (!fields.has(property.schemaName)) fields.set(property.schemaName, property.name);
+    }
+    target = Object.getPrototypeOf(target);
+  }
+  return fields;
+}
+
+function boundedFields(input, type, fields, validators) {
+  const bounded = new Map();
+  for (const [name, field] of Object.entries(type.getFields())) {
+    const propertyName = fields.get(name);
+    const where = `${input.name}.${name}`;
+    if (propertyName === undefined) throw new Error(`${where}: cannot resolve backend input property`);
+    const bounds = boundsOf(validators.filter(validator => validator.propertyName === propertyName), where);
+    validateFieldBounds(field.type, bounds, where);
+    if (Object.keys(bounds).length) bounded.set(name, bounds);
+  }
+  return bounded;
+}
+
+/** Bounds by schema input name and schema field name, using Nest's class/property names only to find validators. */
+export function graphqlInputBounds({ schema, typeStorage, validationStorage }) {
+  const inputs = new Map(typeStorage.getInputTypesMetadata().map(input => [input.target, input]));
+  const result = new Map();
+  const names = new Set();
+  for (const input of inputs.values()) {
+    const type = schema.getType(input.name);
+    if (!type?.getFields) continue;
+    if (names.has(input.name)) throw new Error(`${input.name}: duplicate backend input type name`);
+    names.add(input.name);
+    const validators = validationStorage.getTargetValidationMetadatas(input.target, '', false, false);
+    const bounded = boundedFields(input, type, inputFields(inputs, input), validators);
+    if (bounded.size) result.set(input.name, bounded);
+  }
+  return result;
+}
+
+/** Adds directive AST nodes without changing the schema's types, fields or ordering. */
+export function withInputBounds(document, bounds) {
+  if (!bounds.size && !document.definitions.some(definition => definition.kind === 'InputObjectTypeDefinition')) return document;
+  const nameNode = value => ({ kind: 'Name', value });
+  const definitions = document.definitions.map(definition => {
+    const fields = definition.kind === 'InputObjectTypeDefinition' ? bounds.get(definition.name.value) : null;
+    if (!fields) return definition;
+    return { ...definition, fields: definition.fields.map(field => {
+      const limits = fields.get(field.name.value);
+      if (!limits) return field;
+      const args = ARGUMENTS.filter(name => limits[name] !== undefined).map(name => {
+        const value = limits[name];
+        const integer = INPUT_BOUND_ARGUMENTS[name] === 'Int';
+        if (integer && value > 2147483647) throw new Error(`${definition.name.value}.${field.name.value}: ${name} exceeds GraphQL Int`);
+        return { kind: 'Argument', name: nameNode(name), value: { kind: integer ? 'IntValue' : 'FloatValue', value: String(value) } };
+      });
+      return { ...field, directives: [...(field.directives ?? []), { kind: 'Directive', name: nameNode(INPUT_BOUNDS_DIRECTIVE), arguments: args }] };
+    }) };
+  });
+  const definition = {
+    kind: 'DirectiveDefinition', name: nameNode(INPUT_BOUNDS_DIRECTIVE), repeatable: false,
+    arguments: [
+      { kind: 'InputValueDefinition', name: nameNode(INPUT_BOUNDS_VERSION_ARGUMENT), type: { kind: 'NamedType', name: nameNode('Int') }, defaultValue: { kind: 'IntValue', value: String(INPUT_BOUNDS_VERSION) }, directives: [] },
+      ...ARGUMENTS.map(name => ({ kind: 'InputValueDefinition', name: nameNode(name), type: { kind: 'NamedType', name: nameNode(INPUT_BOUND_ARGUMENTS[name]) }, directives: [] })),
+    ],
+    locations: [nameNode('INPUT_FIELD_DEFINITION')],
+  };
+  if (definitions.some(item => item.kind === 'DirectiveDefinition' && item.name.value === INPUT_BOUNDS_DIRECTIVE)) throw new Error(`@${INPUT_BOUNDS_DIRECTIVE} is reserved for emitted input bounds`);
+  return { ...document, definitions: [definition, ...definitions] };
+}

package/emit/input-bounds.mjs

@@ -0,0 +1,44 @@
+/** Input-bounds contract metadata and class-validator bounds for the GraphQL emitter. */
+export const INPUT_BOUNDS_DIRECTIVE = 'inputBounds';
+export const INPUT_BOUNDS_VERSION = 1;
+export const INPUT_BOUNDS_VERSION_ARGUMENT = 'version';
+export const INPUT_BOUNDS_OPENAPI_EXTENSION = 'x-input-bounds';
+export const INPUT_BOUND_ARGUMENTS = Object.freeze({
+  maxLength: 'Int', maxItems: 'Int', min: 'Float', max: 'Float',
+  itemMaxLength: 'Int', itemMaxItems: 'Int', itemMin: 'Float', itemMax: 'Float',
+});
+export const JSON_SCHEMA_BOUND_KEYS = Object.freeze({ min: 'minimum', max: 'maximum' });
+
+const VALIDATORS = {
+  maxLength: ['maxLength', 'max'],
+  arrayMaxSize: ['maxItems', 'max'],
+  min: ['min', 'min'],
+  max: ['max', 'max'],
+};
+
+/** The tightest bound of each kind, retaining whether class-validator applies it to collection items. */
+export function boundsOf(validators, where) {
+  const bounds = {};
+  for (const validator of validators) {
+    if (!Object.hasOwn(VALIDATORS, validator.name)) continue;
+    const rule = VALIDATORS[validator.name];
+    const [name, direction] = rule;
+    const value = validator.constraints?.[0];
+    if (typeof value !== 'number' || !Number.isFinite(value) || (/Length$|Items$/.test(name) && (!Number.isSafeInteger(value) || value < 0))) {
+      throw new Error(`${where}: ${validator.name} needs a finite${/Length$|Items$/.test(name) ? ' nonnegative integer' : ' numeric'} bound`);
+    }
+    const key = validator.each ? `item${name[0].toUpperCase()}${name.slice(1)}` : name;
+    bounds[key] = bounds[key] === undefined ? value : direction === 'min' ? Math.max(bounds[key], value) : Math.min(bounds[key], value);
+  }
+  for (const prefix of ['', 'item']) {
+    const key = name => prefix ? `${prefix}${name[0].toUpperCase()}${name.slice(1)}` : name;
+    if (bounds[key('min')] > bounds[key('max')]) throw new Error(`${where}: ${key('min')} exceeds ${key('max')}`);
+  }
+  return bounds;
+}
+
+/** A bound must constrain the GraphQL field's scalar or collection-item type. */
+export function validateBoundType(type, key, where) {
+  const expected = key === 'maxItems' ? ['array'] : key === 'min' || key === 'max' ? ['number', 'integer'] : ['string'];
+  if (!expected.includes(type)) throw new Error(`${where}: ${key} requires ${expected.join(' or ')}, found ${type ?? 'an unknown type'}`);
+}

package/emit/operation-schemas.mjs

@@ -0,0 +1,137 @@
+/** Read only the schema declarations of an operation; importing the app table never boots the app during emit. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import vm from 'node:vm';
+
+/** The longest value of each fixed-format string that R305 leaves without an explicit bound; the emit publishes it as maxLength. */
+const FIXED_FORMAT_MAX = Object.freeze({ uuid: 36, guid: 36, cuid: 25, ulid: 26, nanoid: 21, ksuid: 27, xid: 20, ipv4: 15, ipv6: 45, e164: 16 });
+
+/** Reject schemas whose wire values remain unconstrained. */
+function assertClosedShape(schema, location) {
+  if (!schema || typeof schema !== 'object' || (!schema.type && !schema.enum && !Object.hasOwn(schema, 'const') && !schema.anyOf && !schema.oneOf && !schema.allOf)) {
+    throw new Error(`${location}: an open schema (any or unknown) is not an operation wire value`);
+  }
+  if (schema.additionalProperties === true) throw new Error(`${location}: an open object is not an operation wire value`);
+  if (schema.properties && schema.additionalProperties === undefined && schema.patternProperties === undefined) {
+    throw new Error(`${location}: an open object is not an operation wire value; use z.strictObject so unknown keys are refused`);
+  }
+}
+
+/** A runtime bound must survive the JSON conversion; custom refinements alone cannot publish a bounded contract. */
+function assertEmittedBounds(schema, location) {
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const bounded = (keyword) => Number.isFinite(schema[keyword]) && schema[keyword] >= 0;
+  if (types.includes('string') && !schema.enum && !Object.hasOwn(schema, 'const') && !bounded('maxLength')) {
+    throw new Error(`${location}: the string bound must be representable as maxLength in JSON Schema`);
+  }
+  if (types.includes('array') && !bounded('maxItems')) throw new Error(`${location}: the array bound must be representable as maxItems in JSON Schema`);
+  const dictionary = (schema.additionalProperties && typeof schema.additionalProperties === 'object') || schema.patternProperties;
+  if (dictionary && !bounded('maxProperties')) {
+    throw new Error(`${location}: the dictionary bound must be representable as maxProperties in JSON Schema; custom refinements are not emitted by z.toJSONSchema`);
+  }
+}
+
+/** The wire-bearing descendants of a JSON schema, each with an actionable field path. */
+function* schemaChildren(schema, location) {
+  for (const keyword of ['anyOf', 'oneOf', 'allOf', 'prefixItems']) {
+    for (const [index, child] of (schema[keyword] ?? []).entries()) yield [child, `${location}.${keyword}[${index}]`];
+  }
+  for (const [name, child] of Object.entries(schema.properties ?? {})) yield [child, `${location}.${name}`];
+  for (const [pattern, child] of Object.entries(schema.patternProperties ?? {})) yield [child, `${location}.${pattern}`];
+  if (schema.propertyNames) yield [schema.propertyNames, `${location}.key`];
+  if (schema.items) yield [schema.items, `${location}[]`];
+  if (schema.additionalProperties && typeof schema.additionalProperties === 'object') yield [schema.additionalProperties, `${location}.*`];
+}
+
+function assertClosedJsonSchema(schema, location) {
+  assertClosedShape(schema, location);
+  assertEmittedBounds(schema, location);
+  for (const [child, childLocation] of schemaChildren(schema, location)) assertClosedJsonSchema(child, childLocation);
+}
+
+/** Loads schema-only modules and converts their exported zod values with the app's own z.toJSONSchema. */
+export function operationSchemaReader({ ts, program, repoRoot }) {
+  const checker = program.getTypeChecker();
+  const requireApp = createRequire(path.join(repoRoot, 'package.json'));
+  const loaded = new Map();
+  const actual = (symbol) => symbol?.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+  const unwrap = (node) => {
+    while (node && (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
+    return node;
+  };
+  const initializer = (node, seen = new Set()) => {
+    node = unwrap(node);
+    if (node && (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node))) {
+      const declaration = actual(checker.getSymbolAtLocation(node))?.valueDeclaration;
+      const value = declaration && valueOf(declaration);
+      if (value && !seen.has(declaration)) {
+        seen.add(declaration);
+        return initializer(value, seen);
+      }
+    }
+    return node;
+  };
+  const valueOf = (property) => {
+    if (!property || !ts.isShorthandPropertyAssignment(property)) return property?.initializer;
+    const value = actual(checker.getShorthandAssignmentValueSymbol(property));
+    return value?.valueDeclaration?.initializer && !value.valueDeclaration.getSourceFile().fileName.endsWith('.schema.ts')
+      ? value.valueDeclaration.initializer
+      : value?.valueDeclaration?.name ?? property.name;
+  };
+  const schemaSymbol = (node, seen = new Set()) => {
+    node = unwrap(node);
+    const symbol = node && actual(checker.getSymbolAtLocation(node));
+    const declaration = symbol?.valueDeclaration;
+    if (!declaration || seen.has(declaration)) return null;
+    if (declaration.getSourceFile().fileName.endsWith('.schema.ts')) return symbol;
+    seen.add(declaration);
+    return declaration.initializer ? schemaSymbol(declaration.initializer, seen) : null;
+  };
+  function load(file) {
+    if (loaded.has(file)) return loaded.get(file).exports;
+    if (!file.endsWith('.schema.ts')) throw new Error(`schema dependencies must be *.schema.ts, found ${file}`);
+    const source = program.getSourceFile(file)?.text ?? fs.readFileSync(file, 'utf8');
+    const compiled = ts.transpileModule(source, { fileName: file, compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.CommonJS, esModuleInterop: true } }).outputText;
+    const module = { exports: {} };
+    loaded.set(file, module);
+    const requireSchema = (specifier) => {
+      if (/^zod(?:\/|$)/.test(specifier)) return requireApp(specifier);
+      const resolved = ts.resolveModuleName(specifier, file, program.getCompilerOptions(), ts.sys).resolvedModule?.resolvedFileName;
+      if (!resolved?.endsWith('.schema.ts')) throw new Error(`schema modules may import only zod and *.schema.ts, found ${specifier} in ${file}`);
+      return load(resolved);
+    };
+    new vm.Script(compiled, { filename: file }).runInNewContext({ module, exports: module.exports, require: requireSchema }, { timeout: 1000 });
+    return module.exports;
+  }
+
+  return (property, label) => {
+    const entry = initializer(valueOf(property.valueDeclaration));
+    const options = entry && ts.isCallExpression(entry) ? initializer(entry.arguments[0]) : null;
+    const field = options && checker.getTypeAtLocation(options).getProperty(label)?.getDeclarations()?.find((item) => ts.isPropertyAssignment(item) || ts.isShorthandPropertyAssignment(item));
+    const reference = field && unwrap(valueOf(field));
+    if (!reference) throw new Error(`${label}: declare input and output zod schemas in *.schema.ts and pass { input, output } to query or mutation`);
+    const symbol = schemaSymbol(reference);
+    const declaration = symbol?.valueDeclaration;
+    const sourceFile = declaration?.getSourceFile();
+    if (!sourceFile?.fileName.endsWith('.schema.ts')) throw new Error(`${label}: the schema must be an exported declaration from *.schema.ts`);
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    const exported = moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((item) => actual(item) === symbol);
+    if (!exported) throw new Error(`${label}: the schema must be exported from ${sourceFile.fileName}`);
+    const schema = load(sourceFile.fileName)[exported.getName()];
+    // Inline reused schemas and refuse cycles: a recursive value has no bounded wire depth, and a local $ref would point at
+    // the OpenAPI document root instead of this nested schema. Unrepresentable values (Date, transforms) also fail closed.
+    const json = requireApp('zod').z.toJSONSchema(schema, {
+      io: label, target: 'draft-2020-12', cycles: 'throw', reused: 'inline',
+      // A request property marked readOnly would tell OpenAPI clients not to send it; a fixed-format string carries its real maximum.
+      override: ({ jsonSchema }) => {
+        if (label === 'input') delete jsonSchema.readOnly;
+        const fixed = FIXED_FORMAT_MAX[jsonSchema.format];
+        if (jsonSchema.type === 'string' && fixed && jsonSchema.maxLength === undefined) jsonSchema.maxLength = fixed;
+      },
+    });
+    delete json.$schema;
+    assertClosedJsonSchema(json, label);
+    return json;
+  };
+}

package/emit/operations-worker.mjs

@@ -1,6 +1,6 @@
 // The child process of `starci app emit` for the operations of one app.
 // Prints the OpenAPI 3.1 document of the app's typed operation table on stdout; exit 3 when the app has no `apps/<app>/src/operations.ts`.
-// Loads the repository's own typescript (resolved from the repository, never from hfs). Nothing of the repository is executed.
+// Loads the repository's own TypeScript and zod. Only *.schema.ts modules are evaluated; the app is never booted.
 import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -15,7 +15,7 @@ const ts = createRequire(path.join(repoRoot, 'package.json'))('typescript');
 const options = compilerOptionsOf(ts, repoRoot, (message) => process.stderr.write(`stand-in ${message}\n`));
 const program = ts.createProgram({ rootNames: [file], options });
 try {
-  const { operations, components } = readOperations({ ts, program, file });
+  const { operations, components } = readOperations({ ts, program, file, repoRoot });
   process.stdout.write(openApiText({ app, operations, components }));
 } catch (error) {
   process.stderr.write(`${error.message}