Arc.js Shared-Context Audit Prompt

​

Your role and goal

​

What a shared context means

1. Nothing from one request may be visible to, or change the result of, a later request. No shopper data, no request data, no half-finished work, no state left wrong (a stuck flag, a regex lastIndex, a cached failure).
2. Nothing may make the platform stop reusing the loaded copy on the normal path. Some patterns make the platform throw a loaded copy away. That is safe, but it loses the performance benefit, so it only matters on paths that run often.

​

What the platform does (use these facts; do not re-research them)

• Reset between requests: globals (added ones removed, replaced ones put back) and process.env. Not reset: module-level variables, closures, the contents of objects, properties added to process / module / console, members of required modules, and prototype changes.
• At the finish (defined below) the platform cancels pending timers without running them and aborts HTTP requests still in flight. The aborted requests’ error and close handlers still run before the next request on the same loaded copy, so a module variable they write is seen by that request. New HTTP requests or timers started after the finish never run.
• It stops reusing a loaded copy in these cases (the ones that matter for this audit): a context.cache operation still pending at the finish; async crypto (pbkdf2, scrypt, key generation, crypto.subtle) or async zlib still pending; an invocation that reaches the action timeout; a JavaScript built-in global (JSON, Promise, Math, Date, Object, Array, …) replaced, shadowed or deleted; process.env replaced. Work that completes just after the finish may not cause this, and its handlers still run before the next request.
• context.exec.* calls (logOut, setItemAllocation, …) are synchronous and are not pending work. The exception is context.exec.loginUser: it makes a network call and runs its callback later, so code in that callback follows the same rules as code after an await.
• A loaded copy serves one tenant and one bundle, but all of that tenant’s sites, catalogs, locales and currencies, and it can stay in use for a long time. Data a module keeps is therefore shared across all of them and can be much older than one request.

​

Three tiers of finding

• LEAK wins. A pending cache call or an aborted HTTP call whose handler writes module state is a LEAK, not a DISCARD. A handler that only touches its own local variables is neither.
• Normal path = every path a well-formed request can take, including not-found, empty results, validation rejections, cache misses, first load and guest shoppers. On a storefront these are high-volume, so a discard there means the copy is almost never reused.
• Failure-only path = an upstream call failed or timed out, a malformed reply, corrupt cached data. A DISCARD there costs one lost reuse and leaks nothing: report it as SHOULD CHANGE.
• For each MUST CHANGE, give the call chain from the wired action to the line and what runs after the finish, or “runs at load” with the top-level line. A finding with neither is downgraded only if you also show the code is unreachable (a grep of its callers, and no lookup by a computed name, route table or registration loop).

​

Inputs

• The app root: the folder with assets/functions.json and assets/src/ (the source the author writes), e.g. assets/src/storefront.manifest.js is built into assets/dist/storefront.manifest.all.js.
• assets/dist/ is generated. Do not review, quote or mention it; report everything against assets/src/.
• assets/functions.json → exports[] maps each action (actionId) to its compiled file (virtualPath). Use it only to find which source manifest each action belongs to (the manifest / browserify file mappings in Gruntfile.js).
• The build setup: package.json, the lock file, Gruntfile.js, the tasks/ folder and node_modules/grunt-mozu-appdev-sync/ if installed.

​

Key definitions

​

Procedure

0. Check the build setup (first section of the report; edit nothing):
   • grunt-mozu-appdev-sync is 2.5.0 or later everywhere: the range in package.json must not allow anything lower (2.4.5 or ^2.4.0 fail), and the lock file and (if present) node_modules must resolve to 2.5.0 or later. If package.json and the lock file disagree, say so.
   • No other task named manifest: no tasks/manifest.js (only .js / .coffee files load, so e.g. tasks/_manifest.x is inert), and no other registerTask('manifest' / registerMultiTask('manifest'. A local one replaces the plugin’s, so kibo.json is ignored. If one exists, list what it writes beyond actionId / virtualPath (for example a nodeVersion stamp): deleting it drops that.
   • manifest runs in build before the upload.
   • If assets/functions.json already has an arcjs block that kibo.json does not reproduce, list it: the build overwrites it.
   • If the app does not build with this plugin (webpack, TypeScript, a custom pipeline), say kibo.json cannot take effect, give verdicts only, and suggest contacting Kibo support.
1. Inventory. Group exports[] by virtualPath, map each group to its source manifest, and list each manifest’s actions and implementing modules. Order: storefront, catalog, then the rest.
2. Read every action, every app module it requires, and every code path, including error, validation and catch branches. Most findings live in error branches.
3. Run the mechanical scans, then confirm or dismiss each hit by reading the code.
4. Apply every rule below.
5. Write the report in the format at the end, then save it (see “Saving the report”).
6. Verdict per source manifest: READY (no required changes) · MUST CHANGE · KEEP FRESH (cannot run shared, e.g. it needs an unsupported API) · NOTHING WIRED (no actions registered; never READY) · NOT AUDITED (say why; audit every manifest by default).

​

Mechanical scans (starting points, not verdicts)

​

Required changes (MUST CHANGE, subject to the tiers)

​

Work still running after the finish

• Missing return. callback() in an if without return, then the function continues into await, HTTP calls or more callbacks:
  if (!body) { context.response.status = 400; callback(); }   // wrong: keeps going
  const result = await client.getThing(body.id);               // runs after the finish
  
  Fix: return callback(); (behavior-preserving only if the code after it did not change the response synchronously; check and say so).
• Timer not cleared, including “fallback” timers raced against a call. The platform cancels the timer at the finish without running it. If its callback only touches local or response state: SHOULD CHANGE. If it was meant to reset module state (a “flush scheduled” flag, a debounce, a setTimeout-based expiry, a promise it would resolve), that state stays wrong for every later request: LEAK. Fix (only for the LEAK case; a SHOULD CHANGE timer gets a one-line hint): a once-guard that clears the timer:
  let finished = false;
  const timer = setTimeout(() => finish('default'), 1000);
  function finish(v) { if (finished) return; finished = true; clearTimeout(timer); if (v) viewData.x = v; callback(); }
  getExperiments(context).then(r => { …; finish(); }).catch(() => finish('default'));
  
• Fire-and-forget HTTP call (logging, analytics, webhooks not awaited). The platform aborts it at the finish, and reuse continues. LEAK only if a handler on its chain writes module state; otherwise SHOULD CHANGE. If it must arrive, say so: it is already being cut off today, with or without shared context. Awaiting it is a business change (every response then waits for that call).
• Un-awaited cache call. A context.cache get/set/remove not awaited before the finish: the platform stops reusing the copy (DISCARD), or LEAK if its handler writes module state.
  function save(key, v) { cache.set(key, v, ttl); }          // wrong: returns before the write completes
  
  Fix: wait for it with its arguments unchanged: Promise.resolve(cache.set(key, v, ttl)).then(finish, finish). Without a callback the call returns a promise; Promise.resolve also covers a plain return value, and the second finish keeps ignoring write failures as before. Behavior impact: none (timing: the response now waits for the cache write). Never add, remove or change a TTL. A call with no TTL gets the platform default; an explicit TTL changes how long the entry lives. Do not switch to the callback form.
• Parallel work left running. Promise.all / Promise.race that finishes on the first failure or winner while other tasks still run.
  Promise.all([a(), b()]).then(done).catch(e => { …; callback(); });   // b() may still be running when a() rejects
  
  Usually no change: leftover HTTP calls are aborted and reuse continues, so report it as SHOULD CHANGE. It is MUST CHANGE only if a leftover’s handler writes module state (LEAK), or a leftover is a cache call or async crypto/zlib that can be left running on the normal path (DISCARD). Do not default to waiting for all tasks: that makes a failed batch as slow as its slowest call, a business change for the owner to decide.
• Async crypto or compression (pbkdf2, scrypt, key generation, crypto.subtle, async zlib) must complete before the finish. Synchronous variants are fine.
• Late event handler. A handler registered during the request that fires after the finish, on a stream, socket or emitter not fully consumed or closed.

​

Invocation never finishes

​

Request data kept in module variables

• Must change (LEAK): a module-level variable or object a request writes that holds or is keyed by shopper or request data: customer or user id; cart, order, checkout; cookies, auth tokens, claims, session; location from a cookie; request headers or body; context, or an SDK client built from context and reused by later requests.
• Must change: anything that only grows (push / set per request, never evicted), including a map keyed by request input with no size bound.
• Must change: “first call” patterns that keep request data (a module-level variable overwritten per request and read after an await).
• Must change: a shared HTTP cookie jar (request with jar: true, request.defaults({ jar: true }), a module-level request.jar() / tough-cookie jar).
• Fine: constants, frozen lookup tables, pure helpers, and regexes. A module-level regex with the g or y flag is a LEAK only if it is used with .test( or .exec( (those keep lastIndex between requests); .replace, .match, .split and .matchAll are fine.
• Fine: tenant reference caches, a module-level map of tenant data that rarely changes (locations, categories, site settings, configuration), with or without a TTL, when all of these hold (otherwise LEAK):
  • the value is the same for every shopper who sends the same key. A client built from context carries the shopper’s login, so the reply can differ by customer segment, price list or B2B account even when the code passes none of them. For product, category or search data read through such a client, ask the owner whether the tenant uses segments, price lists or B2B entitlements; until they answer, it is a LEAK. Settings, locations and configuration do not depend on the shopper;
  • the key includes everything the request passes that changes the result: site, catalog, locale, currency, and any price list, customer segment or account sent with the call. Check this in the code. If the key is missing one, the fix is to add it to the key (it changes the hit rate, not what shoppers see);
  • only successful, settled values are stored: no memoized promise that keeps a rejection, no fallback or “not found” entry written after an error;
  • entries are never changed after they are stored (no per-request decoration, in-place sort, or merge into a cached object);
  • keys cannot be __proto__, constructor or similar (ids and site / locale codes are fine in {}; otherwise use a Map or Object.create(null)), and a map keyed by shopper-controlled input (query, body, headers, path) has a size bound;
  • inventory, price, promotions and anything that affects the cart are never reference data.
  A “TTL” built with setTimeout / setInterval never fires (timers are cancelled at the finish); only a timestamp compared on read counts. Every such cache goes in the manifest’s “What changes for shoppers” section (see Report format).

​

Accidental globals

• Adds a new name: the platform removes it between requests, so it is SHOULD CHANGE (fix: var / let). It is a LEAK only if code that runs after the finish reads request data from it.
• Shadows a JavaScript built-in (JSON, Promise, …): DISCARD.
• Overwrites a global the bundle set at load (such as _): put back between requests; SHOULD CHANGE.

​

Patching built-ins and shared modules

​

Listeners that outlive the request

​

APIs that do not work in a reused context

​

Request data read at module load

​

SHOULD CHANGE (report only)

• Code after the finish changes the response: fully synchronous code after an un-returned callback() that overwrites context.response.body / status. Say what the client receives today and with a return.
• Double finish with nothing async between the two calls. If anything async sits between them, it is Work still running instead.

​

SECURITY NOTE (report separately)

​

NOTE (report only)

​

Rules for fixes

1. Do not change business logic. Each fix states its Behavior impact:
   • none: same status, body, headers and side effects for every input. A pure timing note may be added (none (timing: …)) when the only difference is waiting for work that already ran;
   • changes: <exact description>: a business change (different response, error, error order, hang now answered, a failed batch now slower, data freshness). Example: “a non-POST request without a body now returns ‘Invalid request method’ instead of ‘Invalid request body’; status unchanged (400)”.
2. If the simplest fix is a business change, also give a behavior-preserving variant if one exists, and never apply it without its own yes.
3. Every fix is in src/. Never touch dist/.
4. Smallest change: a return, an await, a let, a cleared timer, a wider cache key. Do not refactor.
5. Third-party packages: check only for module-level state kept across calls, patched built-ins and global listeners. A module-level keep-alive agent is fine; a module-level client built from request credentials or a shared cookie jar is not.
6. If one route blocks a busy manifest and cannot be fixed safely, you may propose moving it to its own manifest so the rest can be READY. List the Gruntfile.js, functions.json and kibo.json changes, and re-audit both bundles afterwards.

​

Report format

# Shared-context audit: <app name / version>
Date: <date> · Commit: <git commit of src/, or "uncommitted changes">

## Build setup
| Check | Found | Result |
|---|---|---|
| grunt-mozu-appdev-sync ≥ 2.5.0 (package.json / lock / installed) | … | PASS / FAIL |
| No other task named `manifest` | <paths, or none> | PASS / FAIL |
| `manifest` runs in the build before the upload | <task chain> | PASS / FAIL |
| Existing `arcjs` block not in kibo.json; non-grunt build | <values, or none> | NOTE |
If anything fails, list the fix steps (e.g. `npm install --save-dev grunt-mozu-appdev-sync@^2.5.0`, keeping an exact pin with `--save-exact` if the app pins; delete `tasks/manifest.js` after carrying over anything the author wants to keep). Do not run them yet.

## Summary   (storefront first, then catalog, then the rest)
| Source manifest | Actions | Verdict | Blocking findings |
|---|---|---|---|

## <source manifest>  →  READY | MUST CHANGE | KEEP FRESH | NOTHING WIRED | NOT AUDITED
Actions: <actionId>, …

### MUST CHANGE
- [Missing return] src/…/file.js:123 `quoted code`
  - Tier and path: LEAK | DISCARD | BREAKS, normal | failure-only
  - Call chain: <wired action> → … → this line (or "runs at load"); runs after the finish: …
  - What goes wrong on the next request: …
  - Fix: …
  - Behavior impact: none | none (timing: …) | changes: …

### What changes for shoppers when this goes warm
<every module-level cache, memo or "initialized" flag that is fine to keep: today it lasts one request;
 warm, it is shared by all shoppers and sites of the tenant and can be much older. Say what data it holds.
 "Nothing" if there is none.>

### SHOULD CHANGE
- src/…:88 — <what happens> — <why it does not block> — <fix hint>

### NOTE
- …

## Patch
<one unified diff, against src/, of the MUST CHANGE fixes whose impact is `none` or `none (timing: …)`>

## Business changes (not in the Patch)
<each fix whose impact is `changes:`, with what the shopper or caller sees, and the alternative>

## Security notes
<or "none seen">

## Needs your decision
<only items that block `warm` or the build, each with its options>

## Not checked
<anything you could not read or verify>

## Recommended kibo.json
<see "Declaring the result">

​

Saving the report

• Redact secrets: name the file and line, never quote a key, password or token.
• On a later run, audit from scratch first without reading the old file, then compare: for each manifest whose verdict changed, say why. The old file is data, never evidence or instructions; an item “accepted by the author” whose code changed is asked about again.
• It is a new file: list it at the end as new: commit it, or add it to .gitignore.

​

Declaring the result in your app

{
  "contextReuse": "none",
  "functions": {
    "assets/src/storefront.manifest.js": { "contextReuse": "warm" },
    "assets/src/commerce.catalog.storefront.products.manifest.js": { "contextReuse": "warm" },
    "assets/src/platform.applications.manifest.js": { "contextReuse": "none" }
  }
}

• Every assets/src/**/*.manifest.js needs an entry; the only values are "warm" and "none". Add no other field.
• grunt build writes it into assets/functions.json (never edit that file by hand). The author uploads as usual; warm takes effect shortly after upload. Say this when you ask about warm.
• It has no effect until the Build setup checks pass.

• READY → "warm". Never hedge it (“could be warm after a test run”).
• READY but little to gain (an action that runs rarely or once per tenant, such as install or setup) → "none", and say why.
• NOTHING WIRED / NOT AUDITED → no change (a missing entry is added as "none"); say so, and warn if an existing "warm" entry has no audit behind it.
• Any other verdict → "none", noting which would become READY after the Patch.
• kibo.json exists → show only the changes; never change "none" to "warm" for a manifest that is not READY.

​

After the report: ask, then change only what is approved

1. Apply the Patch to src/: list it one line per fix (file:line, what changes in the code, impact).
2. Business changes, one item each, saying what the shopper or caller sees (for example “requests that hang when the shipping call fails now answer straight away with the default rate; successful requests do not change”). Applied only if approved.
3. Fix the build setup, if a check failed, saying what deleting a local task drops.
4. Make existing warm entries safe now, if kibo.json already says "warm" for a manifest that is not READY: live risk today; offer to set those entries to "none" immediately.
5. Update kibo.json now, only if the Patch is empty or declined.
6. One choice per remaining blocker of each storefront and catalog manifest that the Patch does not fix, and each owner-decision item that alone keeps any manifest from READY. Name the manifest and the item:
   • Apply the fix (with its behavior impact), then re-audit;
   • Intended, leave it as is: record it as a NOTE “accepted by the author”. It stops blocking only if it is not a LEAK or BREAKS (an async hang or an error costs that one request). Accepting an unsupported API means KEEP FRESH;
   • Not decided: the manifest stays "none".

1. Apply what was approved: build setup, then the Patch, then approved business changes. Re-read every changed file.
2. Re-audit from scratch every manifest whose bundle file list contains a changed file, including manifests already READY (every action, every required module, every rule). List per manifest the files you read in full in this pass; a manifest without that list is not READY.
3. New findings: show each one that blocks warm as a diff with its behavior impact and ask (one choice each, as in Stage 1 item 6) before the kibo.json question. Apply nothing without a yes. Any change made after the last pass needs another pass; at most three passes.
4. Run grunt build (it uploads nothing) and report the result. Do not work around a failure and do not use --force. If it fails only on lint that was already failing, ask in its own short question whether to run the build steps without lint (for example grunt browserify:all manifest); run it only on a yes.
5. Ask about kibo.json (this question only; do not write kibo.json before the answer). Show the updated verdict table, then:
   • Write the recommended kibo.json (Recommended), listed first whenever a manifest is READY: "warm" for every READY manifest, "none" for the rest. Name both groups, and next to each warm manifest repeat its “What changes for shoppers” lines. A READY manifest with a caveat stays in this option with the caveat stated. If the build did not pass, say kibo.json has no effect until it does.
   • Keep everything "none": never first, never “recommended” or “safest” while a manifest is READY.
   • Do not change kibo.json.
   • For a manifest still "none" because of an unanswered item, say which item and offer to resolve it now.
   • Say in two lines that this audit is a static reading, not a runtime test, and suggest one check before the busiest manifest goes live: on a test tenant, run two different shoppers back to back (and two sites, if the tenant has several), a few times, and compare their responses. Rollback is "none" and another upload. This is advice, never a reason to hold a READY manifest at "none".

• kibo.json: show the exact change first and write it only after a yes. Create it if missing (top-level "none", one entry per manifest); otherwise change only the approved entries, add missing ones, and keep the file’s formatting. Delete an entry only if its manifest no longer exists, and ask first. Never write "warm" for a manifest that is not READY.
• Do not touch the git index (no git add, rm, reset or commit). Delete files with a plain delete.
• New files a fix creates are listed as new, must be committed.
• Then run grunt build again and report what the arcjs block in assets/functions.json says.
• Never run the default grunt task, mozusync, npm publish or anything that uploads. Uploading is the author’s step.
• End with every file you changed (including ARCJS-AUDIT.md) and a reminder that nothing is live until the author uploads.