Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/cli/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ async function main(): Promise<void> {
// 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
}

Expand Down
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions apps/documentation/src/content/docs/plans/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
48 changes: 48 additions & 0 deletions packages/generate/src/compile-keywords.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down
68 changes: 51 additions & 17 deletions packages/generate/src/compile-schema.ts
Original file line number Diff line number Diff line change
@@ -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'

Expand Down Expand Up @@ -287,10 +288,15 @@ function constant(node: Record<string, unknown>, 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<string, { whole: boolean; minimum?: number; maximum?: number }> = {
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 },
}
Expand Down Expand Up @@ -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) {
Expand Down
30 changes: 30 additions & 0 deletions packages/generate/src/independent-validator.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down Expand Up @@ -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)
}
})
})
9 changes: 8 additions & 1 deletion packages/generate/src/plan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'

Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion packages/mcp/src/documented-tools.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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' })
Expand Down
6 changes: 5 additions & 1 deletion packages/mcp/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<void> {
export async function startMcpStdio(options: {
root: string
config: LaqiConfig
version: string
}): Promise<void> {
const server = createMcpServer(options)
await server.connect(new StdioServerTransport())
}
14 changes: 12 additions & 2 deletions packages/mcp/src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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',
Expand Down
10 changes: 10 additions & 0 deletions packages/mcp/src/stdio.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down
2 changes: 1 addition & 1 deletion packages/mcp/src/tool-descriptions.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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' })
Expand Down
Loading