diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts index 0a2d6fa..f8f905b 100644 --- a/apps/cli/src/index.ts +++ b/apps/cli/src/index.ts @@ -162,7 +162,7 @@ async function main(): Promise { // the transport. The startup banner goes to stderr. const { startMcpStdio } = await import('@laqi/mcp') console.error(`laqi mcp — serving ${root}`) - await startMcpStdio({ root, config }) + await startMcpStdio({ root, config, version: laqiVersion() }) return } diff --git a/apps/documentation/src/content/docs/plans/2026-10-07-17-post-210-fixes.md b/apps/documentation/src/content/docs/plans/2026-10-07-17-post-210-fixes.md new file mode 100644 index 0000000..4f70dbc --- /dev/null +++ b/apps/documentation/src/content/docs/plans/2026-10-07-17-post-210-fixes.md @@ -0,0 +1,46 @@ +--- +title: Plan 17 — Post-2.1.0 code fixes +--- + +# Plan 17 — Post-2.1.0 code fixes + +**Date:** 2026-10-07 +**Linear:** [NIW2-8](https://linear.app/niway/issue/NIW2-8) — code part only +**Stacked on:** [Plan 16](/plans/2026-10-07-16-docs-housekeeping/) + +Three defects found in the 2.1.0 release review. The ticket's release chores +(release notes on the GitHub release, marking v2.1.0 "Latest", merging #66) are +Cristian's and are not part of this plan. + +## Tasks + +- [x] **`laqi mcp` reports the real version.** `serverInfo.version` is the + literal `"2.0.0"` in `packages/mcp/src/server.ts`. `createMcpServer` and + `startMcpStdio` take the version from the caller; the CLI passes + `laqiVersion()`, which is the published `laqi` package version (build-time + define, or `apps/cli/package.json` from source). `@laqi/mcp`'s own + `package.json` version is private and not release-managed, so it is not + the number to report. Test: over real stdio, `getServerVersion().version` + equals `apps/cli/package.json`'s version. +- [x] **`int64` stays inside the safe-integer range.** `NUMERIC_FORMATS.int64` + gets `±Number.MAX_SAFE_INTEGER` as its width, so a `maximum` of + `9223372036854775807` is clamped to `2^53 − 1` instead of generating ids + that JavaScript cannot hold exactly. Tests: the compiled plan, and the + independent validator over a generated body. +- [x] **A bound outside the format's width is refused.** An `int32` whose + `minimum` is `2^40` (or whose `maximum` is below `−2^31`) has no value at + all; today the out-of-range bound survives clamping because the other + side is absent, and the generator produces values above `2^31`. It is now + refused as `unsatisfiable`, naming the format. The same check covers + `int64` past the safe range. +- [x] **A one-sided bound near the width's edge stays inside it.** With only a + `minimum`, the generator draws from `minimum..minimum + 1000`; near the + top of an `int32` or the safe range that window crosses the edge, so the + maximum is filled with the width's bound in that case only. + +## Follow-ups proposed, not built + +- Serve integers > 2^53 losslessly (a lossless JSON parse/serialize path end to + end). Today they are reported and their files refuse rewrites (#73). +- Install footprint (~92 MB: `effect` ~33 MB, `typescript` ~23 MB): check + whether either can be lazy-loaded or optional. diff --git a/apps/documentation/src/content/docs/plans/index.md b/apps/documentation/src/content/docs/plans/index.md index 1dd1bef..bd7dca2 100644 --- a/apps/documentation/src/content/docs/plans/index.md +++ b/apps/documentation/src/content/docs/plans/index.md @@ -43,6 +43,7 @@ Further plans, past v2.0.0 itself, build on top of it: | 14 | [JSON Schema and adapters](/plans/2026-09-07-14-json-schema-adapters/) | JSON Schema (draft 2020-12) replaces the experimental generation metadata. A response stores the schema its body came from, regenerates from it, and refuses a blind overwrite. Schemas come from pasted TypeScript, JSON Schema, OpenAPI or the project's own code through Standard JSON Schema. Contracts in [json-schema-adapters](/design/json-schema-adapters/). | **Merged** — spec [#62](https://github.com/csdev19/laqi/pull/62), phases 1–2 [#64](https://github.com/csdev19/laqi/pull/64), phases 3–6 [#65](https://github.com/csdev19/laqi/pull/65) | | 15 | [laqi.dev correctness fixes](/plans/2026-10-01-15-page-truth-fixes/) | The eight correctness defects the [2026-10-01 page audit](/product/page-audit-2026-10-01/) found live on laqi.dev — empty demo placeholders, a wrong MCP tool count, two hero badges contradicted by the page itself, YAML advertised where only JSON is accepted, and a version badge stale by construction. Positioning and new sections are excluded by design. | **Merged** — [PR #68](https://github.com/csdev19/laqi/pull/68) | | 16 | [Docs housekeeping](/plans/2026-10-07-16-docs-housekeeping/) | The roadmap, this status column and the spec headers brought back in line with `main`, plus a proposal to derive this column from PR state. | **In review** | +| 17 | [Post-2.1.0 code fixes](/plans/2026-10-07-17-post-210-fixes/) | `laqi mcp` reports the real version; OpenAPI `int64` stays inside the safe-integer range; a bound outside an integer format's width is refused instead of generating out-of-range values. | **In review** | ## Why this order diff --git a/packages/generate/src/compile-keywords.test.ts b/packages/generate/src/compile-keywords.test.ts index ab84167..c9053a2 100644 --- a/packages/generate/src/compile-keywords.test.ts +++ b/packages/generate/src/compile-keywords.test.ts @@ -97,6 +97,54 @@ describe('numbers', () => { }) }) + // A JSON number past 2^53 reaches every JavaScript client as a different + // number. OpenAPI specs routinely write int64's own limits as the bounds. + it('keeps int64 bounds inside the safe-integer range', () => { + expect( + compiled({ + type: 'integer', + format: 'int64', + minimum: -(2 ** 63), // what JSON.parse makes of int64's -9223372036854775808 + maximum: 2 ** 63, // what JSON.parse makes of int64's 9223372036854775807 + }).plan, + ).toEqual({ + kind: 'primitive', + type: 'integer', + number: { minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER }, + }) + }) + + it('refuses a bound that lies wholly outside the format, instead of generating past it', () => { + const tooLow = refused({ type: 'integer', format: 'int32', minimum: 2 ** 40 }) + expect(tooLow.code).toBe('unsatisfiable') + expect(tooLow.message).toContain('"int32"') + expect(tooLow.message).toContain(String(2 ** 40)) + + expect(refused({ type: 'integer', format: 'int32', maximum: -(2 ** 40) }).code).toBe( + 'unsatisfiable', + ) + expect(refused({ type: 'integer', format: 'int32', exclusiveMinimum: 2147483647 }).code).toBe( + 'unsatisfiable', + ) + expect(refused({ type: 'integer', format: 'int64', minimum: 2 ** 60 }).code).toBe( + 'unsatisfiable', + ) + }) + + it('keeps a lone minimum near the top of a format from drawing past it', () => { + expect(compiled({ type: 'integer', format: 'int32', minimum: 2147483000 }).plan).toEqual({ + kind: 'primitive', + type: 'integer', + number: { minimum: 2147483000, maximum: 2147483647 }, + }) + // Far from the edge nothing is added: the generator's own window decides. + expect(compiled({ type: 'integer', format: 'int32', minimum: 0 }).plan).toEqual({ + kind: 'primitive', + type: 'integer', + number: { minimum: 0 }, + }) + }) + it('refuses a numeric format it does not know, by name', () => { const diagnostic = refused({ type: 'integer', format: 'uint128' }) expect(diagnostic.code).toBe('unsupported.keyword') diff --git a/packages/generate/src/compile-schema.ts b/packages/generate/src/compile-schema.ts index 120cef1..1dc6dfd 100644 --- a/packages/generate/src/compile-schema.ts +++ b/packages/generate/src/compile-schema.ts @@ -1,12 +1,13 @@ import { diagnostic, type Diagnostic } from '@laqi/schema' -import type { - ItemsRule, - NumberRule, - Plan, - PlanField, - PlanLiteral, - TextFormat, - TextRule, +import { + DEFAULT_NUMBER_SPAN, + type ItemsRule, + type NumberRule, + type Plan, + type PlanField, + type PlanLiteral, + type TextFormat, + type TextRule, } from './plan' import { MAX_SHAPE_DEPTH, type PrimitiveType } from './shape' @@ -287,10 +288,15 @@ function constant(node: Record, pointer: string, keywords: stri * OpenAPI's numeric formats. Each names how wide the value is stored, never a * shape of its own, so laqi honours them as bounds and wholeness rather than * refusing a spec that writes them on nearly every number. + * + * `int64` is held to the safe-integer range, not to ±2^63: a JSON number past + * 2^53 is read by every JavaScript client as a different number, so laqi never + * generates one. An OpenAPI `maximum: 9223372036854775807` is clamped to + * `Number.MAX_SAFE_INTEGER`. */ const NUMERIC_FORMATS: Record = { int32: { whole: true, minimum: -2147483648, maximum: 2147483647 }, - int64: { whole: true }, + int64: { whole: true, minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER }, float: { whole: false }, double: { whole: false }, } @@ -325,14 +331,42 @@ function number( const step = type === 'integer' ? 1 : Number.EPSILON const exclusiveMinimum = numeric(node, 'exclusiveMinimum', pointer) const exclusiveMaximum = numeric(node, 'exclusiveMaximum', pointer) - const minimum = clampLow( - numeric(node, 'minimum', pointer) ?? bump(exclusiveMinimum, step), - width?.minimum, - ) - const maximum = clampHigh( - numeric(node, 'maximum', pointer) ?? bump(exclusiveMaximum, -step), - width?.maximum, - ) + const statedMinimum = numeric(node, 'minimum', pointer) ?? bump(exclusiveMinimum, step) + const statedMaximum = numeric(node, 'maximum', pointer) ?? bump(exclusiveMaximum, -step) + + // A bound wholly outside the format's width leaves no value at all. Clamping + // cannot catch it when the other side is absent: an int32 with only + // `minimum: 2^40` would keep that minimum and generate past 2^31. + if (width !== undefined) { + const outside = + statedMinimum !== undefined && width.maximum !== undefined && statedMinimum > width.maximum + ? statedMinimum + : statedMaximum !== undefined && + width.minimum !== undefined && + statedMaximum < width.minimum + ? statedMaximum + : undefined + if (outside !== undefined) { + refuse( + 'unsatisfiable', + `the bound ${outside} lies outside what format ${JSON.stringify(format)} holds (${width.minimum}..${width.maximum}), so no value satisfies it`, + pointer, + ) + } + } + + const minimum = clampLow(statedMinimum, width?.minimum) + let maximum = clampHigh(statedMaximum, width?.maximum) + // A lone minimum draws from the window above it; near the top of the + // format that window would cross the format's edge. + if ( + minimum !== undefined && + maximum === undefined && + width?.maximum !== undefined && + minimum + DEFAULT_NUMBER_SPAN > width.maximum + ) { + maximum = width.maximum + } const multipleOf = numeric(node, 'multipleOf', pointer) if (minimum !== undefined && maximum !== undefined && minimum > maximum) { diff --git a/packages/generate/src/independent-validator.test.ts b/packages/generate/src/independent-validator.test.ts index b447df0..21faa50 100644 --- a/packages/generate/src/independent-validator.test.ts +++ b/packages/generate/src/independent-validator.test.ts @@ -79,6 +79,17 @@ describe('every additive keyword laqi claims to honour', () => { maximum: 1e12, }, 'an int64 written on a number': { type: 'number', format: 'int64', minimum: 0.5, maximum: 9.5 }, + 'int64 with the int64 limits as bounds': { + type: 'integer', + format: 'int64', + minimum: -(2 ** 63), // what JSON.parse makes of int64's -9223372036854775808 + maximum: 2 ** 63, // what JSON.parse makes of int64's 9223372036854775807 + }, + 'int32 with a lone minimum near its top': { + type: 'integer', + format: 'int32', + minimum: 2147483000, + }, 'array length': { type: 'array', items: { type: 'integer' }, minItems: 2, maxItems: 4 }, 'unique items': { type: 'array', @@ -130,3 +141,22 @@ describe('every additive keyword laqi claims to honour', () => { }) } }) + +// ajv's int64 format accepts anything up to 2^63, so it cannot catch this: +// the check is that every value survives a JavaScript client unchanged. +describe('an OpenAPI int64 id', () => { + it('never generates a value a JavaScript client would read as a different number', async () => { + const document = { + $schema: DIALECT_2020_12, + type: 'object', + properties: { id: { type: 'integer', format: 'int64', maximum: 2 ** 63 } }, + required: ['id'], + } + const compiled = compileSchema(document) + if (!compiled.ok) throw new Error(JSON.stringify(compiled.diagnostics)) + for (let seed = 0; seed < 50; seed++) { + const body = (await generateFromPlan(compiled.plan, { seed })) as { id: number } + expect(Number.isSafeInteger(body.id), `${body.id} @ ${seed}`).toBe(true) + } + }) +}) diff --git a/packages/generate/src/plan.ts b/packages/generate/src/plan.ts index 264cdde..7fdf7be 100644 --- a/packages/generate/src/plan.ts +++ b/packages/generate/src/plan.ts @@ -33,6 +33,13 @@ export type PlanField = { name: string; plan: Plan; optional: boolean } /** Numeric bounds a document asserted. Absent means the field-name rules decide. */ export type NumberRule = { minimum?: number; maximum?: number; multipleOf?: number } +/** + * How far above a lone `minimum` the generator draws when no `maximum` is + * stated. The compiler reads it too, to keep that window inside a format's + * width. + */ +export const DEFAULT_NUMBER_SPAN = 1000 + /** The string formats laqi generates. `date-time` is not here: it is the `date` primitive. */ export type TextFormat = 'date' | 'email' | 'uri' | 'uuid' @@ -248,7 +255,7 @@ export const generateFromPlanEffect = ( function boundedNumber(rule: NumberRule, type: 'number' | 'integer'): number { const min = rule.minimum ?? 0 - const max = rule.maximum ?? min + 1000 + const max = rule.maximum ?? min + DEFAULT_NUMBER_SPAN if (rule.multipleOf !== undefined) { const step = rule.multipleOf diff --git a/packages/mcp/src/documented-tools.test.ts b/packages/mcp/src/documented-tools.test.ts index 83f0361..a484c15 100644 --- a/packages/mcp/src/documented-tools.test.ts +++ b/packages/mcp/src/documented-tools.test.ts @@ -106,7 +106,7 @@ let root: string beforeAll(async () => { root = mkdtempSync(join(tmpdir(), 'laqi-documented-tools-')) - const server = createMcpServer({ root, config: ConfigSchema.parse({}) }) + const server = createMcpServer({ root, config: ConfigSchema.parse({}), version: '0.0.0-test' }) const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair() client = new Client({ name: 'test', version: '1.0.0' }) diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts index 0edabce..a32847a 100644 --- a/packages/mcp/src/index.ts +++ b/packages/mcp/src/index.ts @@ -12,7 +12,11 @@ export { createMcpServer } from './server' * stdout is the protocol channel: any stray `console.log` corrupts it. * Anything that needs to say something goes to stderr. */ -export async function startMcpStdio(options: { root: string; config: LaqiConfig }): Promise { +export async function startMcpStdio(options: { + root: string + config: LaqiConfig + version: string +}): Promise { const server = createMcpServer(options) await server.connect(new StdioServerTransport()) } diff --git a/packages/mcp/src/server.ts b/packages/mcp/src/server.ts index f873ec1..1dd1c22 100644 --- a/packages/mcp/src/server.ts +++ b/packages/mcp/src/server.ts @@ -52,7 +52,17 @@ function errorMessage(error: unknown): string { return error instanceof Error ? error.message : String(error) } -export function createMcpServer(options: { root: string; config: LaqiConfig }): McpServer { +export function createMcpServer(options: { + root: string + config: LaqiConfig + /** + * The published `laqi` version, reported to the client as + * `serverInfo.version`. The caller passes it because this package's own + * version is private and never released, so it is not the number a user + * installed. + */ + version: string +}): McpServer { const project = new Project(options.root, options.config) /** * MCP never redeems a panel token — it holds this only for the written-down @@ -62,7 +72,7 @@ export function createMcpServer(options: { root: string; config: LaqiConfig }): const approvals = new ModuleApprovals(options.root, options.config) const server = new McpServer( - { name: 'laqi', version: '2.0.0' }, + { name: 'laqi', version: options.version }, { instructions: [ 'laqi is a mock HTTP server. These tools edit the mock definitions in the', diff --git a/packages/mcp/src/stdio.test.ts b/packages/mcp/src/stdio.test.ts index 63d1ca6..5644161 100644 --- a/packages/mcp/src/stdio.test.ts +++ b/packages/mcp/src/stdio.test.ts @@ -95,6 +95,16 @@ describe('laqi mcp over stdio', () => { ]) }) + it('reports the version of the laqi package the user installed, not a literal', async () => { + const cliPackage = JSON.parse( + readFileSync( + join(import.meta.dirname, '..', '..', '..', 'apps', 'cli', 'package.json'), + 'utf8', + ), + ) as { version: string } + expect(client.getServerVersion()).toMatchObject({ name: 'laqi', version: cliPackage.version }) + }) + it('teaches the layer model in its instructions, so the agent does not guess', async () => { const instructions = client.getInstructions() ?? '' expect(instructions).toContain('An override beats the active scenario') diff --git a/packages/mcp/src/tool-descriptions.test.ts b/packages/mcp/src/tool-descriptions.test.ts index 5038f08..d5cad45 100644 --- a/packages/mcp/src/tool-descriptions.test.ts +++ b/packages/mcp/src/tool-descriptions.test.ts @@ -61,7 +61,7 @@ let root: string beforeAll(async () => { root = mkdtempSync(join(tmpdir(), 'laqi-tool-desc-')) - const server = createMcpServer({ root, config: ConfigSchema.parse({}) }) + const server = createMcpServer({ root, config: ConfigSchema.parse({}), version: '0.0.0-test' }) const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair() client = new Client({ name: 'test', version: '1.0.0' })