Effect Guard — ตั้งด่านก่อนเกิดผลจริงGuard Effects and Require Approval — AI-Core + Jev in Practice

Part 7 of ten: Check permissions before effects, bind approval to one payload, and test idempotency in a simulated ledger.

Local review draft • Default code uses offline fixtures. Numbers are fictional scenarios, not measured Jev results. Faster performance and lower cost remain hypotheses.

Outcome and prerequisites

Start with the companion repository and its detailed README. The website ZIP remains an alternative offline snapshot; run the same Node commands from either project root. GitHub repository · README / Quickstart

Use the same Support Ticket Decision Lab throughout the series. Have Node 22.18+, a terminal and a writable directory. Run commands from the cloned ai-core-jev-tutorial root, or the extracted ai-core-jev-lab folder if using the website ZIP. Offline work needs no npm install. Allow roughly 20–40 minutes for experiments; the article reading-time label excludes hands-on work.

Download the complete code and tests (ZIP) · Project README

This chapter focuses on src/effects.mjs. Fixture outputs test the integration mechanics only. The author did not install the SDK or use an API key while preparing the lab. The separately documented live path has not been tested against the API.

How this boundary works

Model output and permission are different data. A high-confidence route proposal does not authorize an external action, and text claiming that a reviewer approved cannot become an approval record. Our deterministic guard checks a closed action name, a known ticket, an allowed queue and a separate approval bound to the exact action and release.

All effects in the lab are simulated JSON-ledger entries. The demo-reviewer identity is a teaching placeholder, not authentication. The serial ledger demonstrates an idempotency check but has no transactional concurrency guarantee. A production service needs authenticated reviewers, tamper-resistant audit, atomic durable storage and a unique-key constraint enforced by its database.

The approval key includes release, ticket ID, action kind and queue. Changing any of those invalidates the approval. This prevents a reviewed billing proposal from being reused for a technical route or another release. Hashing alone does not establish who approved; it merely binds the approval record to a specific payload in this demonstration.

Seven practical steps

Step 1 — Inspect effectGuard before running actions

Inspect effectGuard before running actions. It begins with refusal and returns allow only after every structural condition and the separate approval match. The provider never receives the approval object, so generated content cannot set its own approved flag through the response schema.

Step 2 — Run actions without the approval flag

Run actions without the approval flag. The expected result is blocked with needs_human_approval, and no ledger file should be created by that path. Treat this as a successful refusal test, not as a broken demonstration to be bypassed.

Step 3 — Run the same ticket with explicit demonstration approval and a fresh named ledger

Run the same ticket with explicit demonstration approval and a fresh named ledger. The program creates a simulation entry, not a help-desk API request. Inspect simulation:true before interpreting the word simulated as an action that happened outside the lab.

Step 4 — Repeat the exact approved command against that ledger

Repeat the exact approved command against that ledger. It should return duplicate rather than append another effect. This is the observable contract for serial reruns. Do not infer that the same code handles two simultaneous processes; the implementation explicitly does not make that claim.

Step 5 — Read the changed-queue test

Read the changed-queue test. It makes a valid approval, alters the queue and expects refusal. This matters because approvals should authorize the reviewed payload, not a vague intention such as let the model do something useful with this ticket.

Step 6 — Read the forbidden-action test

Read the forbidden-action test. It changes kind to refund and supplies high confidence. The guard still denies it. Confidence is semantic evidence; the action allow-list is a structural permission boundary. Their responsibilities should not be merged.

Step 7 — Name the production gap before continuing

Name the production gap before continuing. Write down which identity system, transactional store and review interface would replace the placeholders. Until those decisions are implemented and tested, keep the project in simulation or shadow mode. A model benchmark does not close an effect-boundary gap.

Files and commands

Companion code on GitHub: ai-core-jev-tutorial · README. Use the companion repository as the default working copy. These file links pin the tested revision. src/effects.mjs · test/effects.test.mjs

Compare this file with the source in the ZIP before editing. The listing is the implementation used by the lab, not pseudocode. Model output is input to validation and routing code; it grants no permission to bypass approval.

src/effects.mjs

import {createHash} from 'node:crypto';import {readFile,writeFile,mkdir} from 'node:fs/promises';import {dirname} from 'node:path';
import {QUEUES} from './contracts.mjs';
export function approvalKey(action,release) {return createHash('sha256').update(JSON.stringify([release,action.ticketId,action.kind,action.queue])).digest('hex');}
export function effectGuard(proposal,{knownIds,approval,release}) {
  const a=proposal.action;
  if(proposal.status!=='proposed'||!a||a.kind!=='route_ticket')return {allow:false,reason:'unsupported_or_unready'};
  if(!knownIds.has(a.ticketId)||a.ticketId!==proposal.ticketId||!QUEUES.includes(a.queue))return {allow:false,reason:'out_of_scope'};
  const key=approvalKey(a,release);
  if(approval?.key!==key||approval?.reviewer!=='demo-reviewer'||approval?.approved!==true)return {allow:false,reason:'needs_human_approval'};
  return {allow:true,key};
}
export async function simulate(proposal,context,ledger) {
  const gate=effectGuard(proposal,context);if(!gate.allow)return {status:'blocked',reason:gate.reason};
  let rows=[];try{rows=JSON.parse(await readFile(ledger,'utf8'))}catch(e){if(e.code!=='ENOENT')throw e}
  if(rows.some(r=>r.key===gate.key))return {status:'duplicate',key:gate.key};
  rows.push({key:gate.key,release:context.release,...proposal.action,simulation:true});
  await mkdir(dirname(ledger),{recursive:true});await writeFile(ledger,JSON.stringify(rows,null,2)+'\n');return {status:'simulated',key:gate.key};
}
// Teaching ledger: serial, single-process only. Production requires authenticated
// approvals, a transactional unique key and atomic durable writes.

Run these offline commands without an SDK installation or API key:

node src/cli.mjs actions --ticket T-001 --ledger out/chapter7-ledger.json
node src/cli.mjs actions --ticket T-001 --approve --ledger out/chapter7-ledger.json
node src/cli.mjs actions --ticket T-001 --approve --ledger out/chapter7-ledger.json
node --test --test-reporter=spec test/effects.test.mjs

Verify the expected behavior

With a fresh ledger, the three commands should return blocked, simulated and duplicate in order. Re-running a chapter with an existing ledger may start at duplicate; use a new filename to reproduce the first-run sequence. No customer contact or monetary action is implemented.

Read the named tests and refusal paths, not just the exit code or final label. Unknown values must remain unknown, and every report must distinguish simulation inputs from real measurements.

Troubleshooting

If an effect occurs before effectGuard, the architecture is wrong even if tests for the guard pass. If duplicate entries appear in concurrent execution, use a transactional storage design rather than adding a sleep. If approval is loaded from model output, separate it into a trusted application-owned channel.

When previewing with Python http.server, use the .html continuation links below when needed. Extensionless series chips rely on GitHub Pages resolution; that documented preview limitation is separate from the Node example.

Change one thing, then test

Approve one proposal, change its release identifier, and check that the old approval key no longer authorizes it. Then describe how an authenticated reviewer and transactional database would replace the demo placeholders. Do not call the teaching JSON ledger a production approval service.

Make changes in a disposable copy, retain the reference files for comparison, and restore them before the next chapter. If you later use a real provider, create a new experiment record rather than overwriting the fixture transcript.

Next checkpoint

Before moving on, identify the contract file, the policy file, what was observed in a run, and what remains untested against a real model. Keeping those four things separate matters more than making the demo look effortless.

← Previous chapter · Next chapter →

References and evidence

Key takeaways