Contracts — เขียนสัญญาให้ตรวจได้Define Contracts Before Models

Part 2 of twelve. Specify runtime contracts for inputs, model decisions and four gate states before interpreting any answer.

Default decisions and draft text are authored mocks, not live Jev results. Use the tutorial with the matching companion code, tests and exercise linked to a fixed GitHub version.

Outcome and prerequisites

Use Node22.18+ and a terminal. Clone the GitHub companion using its README, or download the complete ZIP, extract it and enter ai-core-functional-lab. No npm install, API key or network inference is needed. The reading-time label excludes about25–45 minutes of hands-on work. Keep one reference copy and make exercises in another.

Download companion ZIP · README / lesson map

This part focuses on src/contracts.mjs. Expected gate states describe content and continuation; no state sends a message or changes a real account.

Old functions and the new boundary

A function signature tells callers what may cross a boundary. At a model boundary, a TypeScript type alone cannot validate bytes returned by an external service. Our JavaScript runtime checks turn that expectation into executable refusal behavior.

The result union has four states: accept, reject, revise and human_review. Revise requests another bounded draft; review stops automated continuation. Neither is an alias for failure to parse, and accept is not permission to send.

The model contract pins jev-1.14.0 and named answer IDs. Choice includes a closed label set, distribution and distribution-derived confidence; Noul returns the probability of yes without a separate confidence field. Unsupported or missing values cause review rather than a guessed default.

Seven practical steps

Step 1

List the boundary fields before reading the parser: model, answers, purpose and injection. Compare that list with request output. The request question IDs determine which answer IDs the caller expects.

Step 2

Follow probability and test NaN, Infinity, a string and an out-of-range number. JavaScript accepting JSON-like values does not make them valid probabilities; finite numeric range checks belong in code.

Step 3

Inspect the Choice label allowlist and require all three probabilities. A selected label must be maximal and the distribution must sum to one within tolerance. A plausible-looking label alone is insufficient.

Step 4

Compare the returned confidence with the documented distribution statistic. That check catches an inconsistent fixture or adapter, not semantic truth. Keep the distinction between contract validity and classification correctness visible.

Step 5

Remove injection from a response in a test and require a refusal. Never convert a missing Noul into zero, because that silently interprets an absent answer as a confident no.

Step 6

Run the V005 input judgment. Its schema is valid but confidence is below the teaching policy boundary, so human_review is the correct continuation. Validation did not promise acceptance.

Step 7

Read the closed gate-state helper and add no execute state. Keeping external operations out of this return type makes the function easier to compose and review. Test unknown states explicitly.

Files and runnable commands

Open the exact source and read its dependencies before editing. This is runnable reference code, not a fictional AI-Core SDK. The source links point to a fixed version of the public GitHub companion.

src/contracts.mjs · Matching tests · This lesson’s exercise

/** @typedef {'accept'|'reject'|'revise'|'human_review'} GateState */
/** Gate outputs describe artifacts, never permission to execute an external effect. */
export function gate(state, reasons=[], value=null) {
  if(!['accept','reject','revise','human_review'].includes(state)) throw new Error('unknown gate state');
  return {state,reasons,value};
}
export function plain(value) {
  return value!==null && typeof value==='object' && !Array.isArray(value)
    && [Object.prototype,null].includes(Object.getPrototypeOf(value));
}
export function probability(value,name='probability') {
  if(typeof value!=='number'||!Number.isFinite(value)||value<0||value>1)
    throw new Error(`invalid ${name}`);
  return value;
}
export const MODEL='jev-1.14.0';
export const PURPOSES=['how_to','account_action','other'];
export function parseDecision(stage,response) {
  if(!plain(response)||response.model!==MODEL||!plain(response.answers))
    throw new Error('missing answers or wrong pinned model');
  const a=response.answers;
  const names=stage==='input'?['purpose','injection']:stage==='output'
    ?['grounded','hiddenInstructions']:stage==='quality'
    ?['answersUser','stepsUsable','plainLanguage']:null;
  if(!names||Object.keys(a).sort().join()!==[...names].sort().join())
    throw new Error('missing or unexpected answer IDs');
  const out={};
  for(const name of names) {
    const x=a[name];
    if(name==='purpose') {
      if(x?.type!=='choice'||!PURPOSES.includes(x.choice)||!plain(x.probabilities)
        ||Object.keys(x.probabilities).sort().join()!==[...PURPOSES].sort().join())
        throw new Error('invalid Choice label or discriminant');
      const values=PURPOSES.map(k=>probability(x.probabilities[k],k));
      if(Math.abs(values.reduce((s,v)=>s+v,0)-1)>1e-5
        ||x.probabilities[x.choice]+1e-8<Math.max(...values)) throw new Error('invalid distribution');
      const confidence=probability(x.confidence,'confidence');
      if(Math.abs(confidence-(Math.max(...values)-1/3)/(1-1/3))>1e-5)
        throw new Error('inconsistent Choice confidence');
      out.purpose={choice:x.choice,confidence,probabilities:{...x.probabilities}};
    } else {
      if(x?.type!=='noul') throw new Error('wrong Noul discriminant');
      out[name]=probability(x.noul,name); // Noul has no separate confidence field.
    }
  }
  return out;
}

Offline commands:

node --test --test-reporter=spec test/contracts.test.mjs
node src/cli.mjs request --stage input --case V001
node src/cli.mjs judge --stage input --case V005

Expected output and verification

All contract tests pass; deliberately mutated response variants throw. V005 returns human_review rather than reject or accept. The fixture model field is the pinned version, so a moving alias response is refused by this example.

Inspect reasons, history and every attempt rather than only the final label. Unknown usage must remain unknown. A green test demonstrates the specified code path, not universal semantic safety.

A failure to understand

A fallback such as answer.injection?.noul ?? 0 turns missing data into evidence for no injection. The missing-answer test exists to prevent that convenient-looking but unsafe default.

Exercise in a disposable copy

Add a contract test for a wrong model, then a negative probability. Confirm both are rejected while a valid Noul without confidence still passes. Do not fix the exercise by adding a fictional API field.

Follow the matching exercise file, retain the original and restore the reference before the next chapter. Do not use held-out results to choose a threshold.

Troubleshooting

A sum mismatch may be floating-point noise or genuinely malformed output. The current tolerance is explicit. Diagnose values and option count before relaxing it, and never repair a distribution by silently renormalizing it.

Next checkpoint

Before continuing, name the property that code checks exactly, the judgment that may be wrong, the state that stops work and the evidence needed before release.

← Previous lesson · Next lesson →

Sources and version notes

Key takeaways