fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument#14459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-musk merged 4 commits into from
Sep 2, 2026
+193 −115
Merged

fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument #14459

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a9c4726
fix(example-showcase): take the sweep's engine off its JobHandlerCont…
claude Sep 2, 2026
7dfba39
test(example-showcase): pin the sweep on an artifact-shaped boot
claude Sep 2, 2026
6aef81f
Merge remote-tracking branch 'origin/main' into claude/issue-14257-sh…
claude Sep 2, 2026
7988dad
test(example-showcase): stop spelling a repo path in the artifact-boo…
claude Sep 2, 2026
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
28 changes: 18 additions & 10 deletions examples/app-showcase/objectstack.config.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -30,7 +30,7 @@ import { CapabilityMapPage, StartHerePage, ComponentGalleryPage, ProjectWorkspac
import { allFlows } from './src/automation/flows/index.js';
import { allWebhooks } from './src/automation/webhooks/index.js';
import { allHooks } from './src/data/hooks/index.js';
import { allJobs, sweepProjectHealth, bindShowcaseJobRuntime } from './src/automation/jobs/index.js';
import { allJobs, sweepProjectHealth } from './src/automation/jobs/index.js';
import { allEmails } from './src/system/emails/index.js';
import { allBooks } from './src/system/books/index.js';
import { allApis } from './src/system/apis/index.js';
Expand DownExpand Up@@ -220,10 +220,19 @@ export default defineStack({
// A JOB handler resolves through this same map (`collectBundleFunctions`), so
// `sweepProjectHealth` — the handler `HealthSweepJob` names — lives here too.
// It is the case the pure contract does not cover: a nightly sweep has no
// downstream declarative node to persist for it, so it writes over an engine
// handle captured at `onEnable`. That is why it is spelled the DECLARED way
// (#4396) — an undeclared writer is counted as having written nothing, which
// is indistinguishable from the broken sweep #4354 exists to detect.
// downstream declarative node to persist for it, so it writes over the `ql`
// handle on its own `JobHandlerContext` argument (#14094). That is why it is
// spelled the DECLARED way (#4396) — an undeclared writer is counted as
// having written nothing, which is indistinguishable from the broken sweep
// #4354 exists to detect. The declaration is about who counts the writes, not
// about where the handle comes from, so it stands unchanged now that the
// handle arrives in the argument.
//
// ⛔ It is NOT reached through an `onEnable` binding any more (#14257). This
// map is the ONLY thing `objectstack build` emits into the runtime module and
// the only thing `mergeRuntimeModule` merges back, so a handler that needed
// `onEnable` to have run first was inert on every artifact-served boot — on
// schedule, silently, reported as a clean run.
//
// This entry authored the bare form until #4976, not because the bare form was
// right but because the declared one could not survive `objectstack build`:
Expand DownExpand Up@@ -292,9 +301,8 @@ export const onEnable = async (ctx: unknown): Promise<void> => {
// real pending requests land in the inbox (cannot be a seed — see
// seed-approval-demo.ts).
registerShowcaseApprovalDemo(ctx as Parameters<typeof registerShowcaseApprovalDemo>[0]);
// Hand the nightly health-sweep job its data handle. A job handler is invoked
// by the job service with `{ jobId, data }` and no engine (flow functions are
// pure by default, #4396), so `onEnable` — the one place the app is handed a
// live engine — is where the sweep gets one.
bindShowcaseJobRuntime(ctx as Parameters<typeof bindShowcaseJobRuntime>[0]);
// ⛔ Nothing here hands the nightly health-sweep job a data handle any more
// (#14257). It takes `ql` and `logger` off its own `JobHandlerContext`
// argument (#14094) — the only route that survives an artifact-served boot,
// which carries no `onEnable` at all. See `src/automation/jobs/`.
};
2 changes: 1 addition & 1 deletion examples/app-showcase/src/automation/jobs/index.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

import { defineJob } from '@objectstack/spec';

export { sweepProjectHealth, bindShowcaseJobRuntime, healthFor } from './sweep-project-health.js';
export { sweepProjectHealth, healthFor } from './sweep-project-health.js';

/**
* Nightly job — recompute project health.
Expand Down
103 changes: 43 additions & 60 deletions examples/app-showcase/src/automation/jobs/sweep-project-health.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -20,22 +20,41 @@
* "never advertise a capability the runtime doesn't deliver" (AGENTS.md Prime
* Directive #10) cuts both ways.
*
* ## Why the engine handle is captured rather than passed in
* ## Where the engine comes from — the ARGUMENT, never a module-scope handle
*
* A job handler is resolved through the SAME `defineStack({ functions })`
* registry as a `script` flow node (`collectBundleFunctions` in
* `@objectstack/runtime`), and the job service invokes it with
* `{ jobId, data }` — `IJobService`'s `JobHandler` context — plus the `bundle`
* the AppPlugin adds. There is deliberately no data engine in that context: a
* flow function is PURE by default, returning a value a later declarative node
* persists (#4343 / #4396).
*
* A background job is the case that contract does not cover — nothing
* downstream is going to persist for it — so it does its own I/O over a handle
* captured at `onEnable`, and DECLARES that in the `functions` map with
* `effect: 'writes'` (#4396). That declaration grants nothing; it tells the
* platform this callable's writes are not counted by the caller, so a run
* reports "cannot say" instead of silently claiming it wrote nothing.
* `@objectstack/runtime`), and a `script` node's context deliberately carries
* no data engine: a flow function is PURE, returning a value a later
* declarative node persists (#4343 / #4396).
*
* A JOB is the case that contract does not cover — it has no graph, so no node
* before it reads and none after it persists. Since #14094 the AppPlugin
* therefore invokes a job's `functions` entry with a `JobHandlerContext`:
* `{ jobId, data, bundle }` widened with `ql` (the same engine handle
* `defineStack({ onEnable })` receives) and `logger`. This handler takes both
* from that argument, which is the only route that survives the shipped
* deployment path.
*
* ⛔ The shape this file used to have — `onEnable` filling a module-scope
* `let host` the handler read later — does NOT survive a built artifact, and
* fails silently rather than loudly. `objectstack build` emits `functions` into
* a sibling runtime module exporting only `{ functions, meta }`; the artifact
* JSON carries no `onEnable`, and `mergeRuntimeModule`
* (`packages/runtime/src/load-artifact-bundle.ts`) merges only `functions`. So
* on an artifact-served boot the binding was never made, the handle stayed
* `undefined`, and `showcase_health_sweep` fired on schedule, recomputed
* nothing, and reported a clean run (#14257). The pin against a return is in
* `test/inert-wirings.test.ts`, which reaches this handler through its
* `functions` entry — the one thing an artifact carries — with no `onEnable`
* anywhere in the test.
*
* The entry still DECLARES `effect: 'writes'` in the `functions` map (#4396),
* and taking `ql` from the argument does not change that: the declaration was
* never about where the handle came from. A job's writes are counted by no
* caller — there is no downstream declarative node to count them — so
* undeclared, a run reports having written nothing instead of "cannot say",
* which is indistinguishable from the broken sweep #4354 exists to detect.
*
* ## What it computes
*
Expand All@@ -56,6 +75,8 @@
* so a steady-state sweep performs zero updates.
*/

import type { JobHandlerContext } from '@objectstack/runtime';

/** Statuses whose health is still in play. */
const SWEPT_STATUSES = ['active', 'on_hold'] as const;

Expand All@@ -71,36 +92,6 @@ const SYS = { isSystem: true } as const;

type Health = 'green' | 'yellow' | 'red';

interface JobHostEngine {
find: (object: string, query: unknown, options?: unknown) => Promise<unknown>;
update: (object: string, data: Record<string, unknown>, options?: unknown) => Promise<unknown>;
}

interface JobHostContext {
ql: JobHostEngine;
logger?: {
info?: (...a: unknown[]) => void;
warn?: (...a: unknown[]) => void;
};
}

/**
* The engine handle the job runs over, captured from the host context at
* `onEnable`. Module scope is what makes it reachable from a `functions` entry,
* which the job service calls with no context of its own — the "closed over a
* client at module scope" shape `effect: 'writes'` exists to declare.
*/
let host: JobHostContext | undefined;

/**
* Give `sweepProjectHealth` its data handle. Called from `onEnable` in
* `objectstack.config.ts`, which is the one place the app is handed a live
* engine. Idempotent — a re-enable simply rebinds.
*/
export function bindShowcaseJobRuntime(ctx: JobHostContext): void {
host = ctx;
}

/** Normalize the engine's list shape (array, or `{ records }`). */
function rowsOf(result: unknown): Array<Record<string, unknown>> {
if (Array.isArray(result)) return result as Array<Record<string, unknown>>;
Expand All@@ -120,7 +111,7 @@ function num(value: unknown): number | undefined {

/**
* The health verdict for one project — exported so the rule is unit-testable
* without an engine (see `test/job-health-sweep.test.ts`).
* without an engine (see `test/inert-wirings.test.ts`).
*/
export function healthFor(input: {
budget?: unknown;
Expand DownExpand Up@@ -148,20 +139,12 @@ export function healthFor(input: {
*
* Registered as `functions.sweepProjectHealth` with `effect: 'writes'` and
* scheduled by `HealthSweepJob` (`0 1 * * *` UTC).
*
* `jobId`, `ql` and `logger` all come off the `JobHandlerContext` the AppPlugin
* builds per run — there is no binding step, so there is no boot path on which
* this handler can be reached without them.
*/
export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void> {
const jobId = ctx?.jobId ?? 'showcase_health_sweep';
if (!host) {
// Reached only if the job somehow fires before `onEnable` bound the
// handle. Functional degradation, not a durability one: nothing claimed to
// be persisted has been lost, and the next scheduled run recomputes
// everything from scratch (AGENTS.md "Degradation log levels").
// eslint-disable-next-line no-console
console.warn(`[showcase] ${jobId}: no engine handle bound yet — skipping this run`);
return;
}
const { ql, logger } = host;

export async function sweepProjectHealth({ jobId, ql, logger }: JobHandlerContext): Promise<void> {
const projects = rowsOf(
await ql.find('showcase_project', {
where: { status: { $in: [...SWEPT_STATUSES] } },
Expand All@@ -171,7 +154,7 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
}),
);
if (projects.length === 0) {
logger?.info?.('[showcase] project health sweep: no in-play projects', { job: jobId });
logger.info('[showcase] project health sweep: no in-play projects', { job: jobId });
return;
}

Expand DownExpand Up@@ -208,15 +191,15 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
await ql.update('showcase_project', { id, health: next }, { context: SYS });
updated += 1;
} catch (err) {
logger?.warn?.('[showcase] project health update failed', {
logger.warn('[showcase] project health update failed', {
job: jobId,
project: id,
error: err instanceof Error ? err.message : String(err),
});
}
}

logger?.info?.('[showcase] project health sweep complete', {
logger.info('[showcase] project health sweep complete', {
job: jobId,
scanned: projects.length,
updated,
Expand Down
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument#14459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-musk
merged 4 commits into

from

Sep 2, 2026

+193

−115

 Merged


fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument
#14459
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a9c4726

fix(example-showcase): take the sweep's engine off its JobHandlerCont…


claude Sep 2, 2026
7dfba39

test(example-showcase): pin the sweep on an artifact-shaped boot


claude Sep 2, 2026
6aef81f

Merge remote-tracking branch 'origin/main' into claude/issue-14257-sh…


claude Sep 2, 2026
7988dad

test(example-showcase): stop spelling a repo path in the artifact-boo…


claude Sep 2, 2026

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


28 changes: 18 additions & 10 deletions
examples/app-showcase/objectstack.config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -30,7 +30,7 @@ import { CapabilityMapPage, StartHerePage, ComponentGalleryPage, ProjectWorkspac
import { allFlows } from './src/automation/flows/index.js';
import { allWebhooks } from './src/automation/webhooks/index.js';
import { allHooks } from './src/data/hooks/index.js';
import { allJobs, sweepProjectHealth, bindShowcaseJobRuntime } from './src/automation/jobs/index.js';
import { allJobs, sweepProjectHealth } from './src/automation/jobs/index.js';
import { allEmails } from './src/system/emails/index.js';
import { allBooks } from './src/system/books/index.js';
import { allApis } from './src/system/apis/index.js';
Expand DownExpand Up@@ -220,10 +220,19 @@ export default defineStack({
 // A JOB handler resolves through this same map (`collectBundleFunctions`), so
 // `sweepProjectHealth` — the handler `HealthSweepJob` names — lives here too.
 // It is the case the pure contract does not cover: a nightly sweep has no
 // downstream declarative node to persist for it, so it writes over an engine
 // handle captured at `onEnable`. That is why it is spelled the DECLARED way
 // (#4396) — an undeclared writer is counted as having written nothing, which
 // is indistinguishable from the broken sweep #4354 exists to detect.
 // downstream declarative node to persist for it, so it writes over the `ql`
 // handle on its own `JobHandlerContext` argument (#14094). That is why it is
 // spelled the DECLARED way (#4396) — an undeclared writer is counted as
 // having written nothing, which is indistinguishable from the broken sweep
 // #4354 exists to detect. The declaration is about who counts the writes, not
 // about where the handle comes from, so it stands unchanged now that the
 // handle arrives in the argument.
 //
 // ⛔ It is NOT reached through an `onEnable` binding any more (#14257). This
 // map is the ONLY thing `objectstack build` emits into the runtime module and
 // the only thing `mergeRuntimeModule` merges back, so a handler that needed
 // `onEnable` to have run first was inert on every artifact-served boot — on
 // schedule, silently, reported as a clean run.
 //
 // This entry authored the bare form until #4976, not because the bare form was
 // right but because the declared one could not survive `objectstack build`:
Expand DownExpand Up@@ -292,9 +301,8 @@ export const onEnable = async (ctx: unknown): Promise<void> => {
 // real pending requests land in the inbox (cannot be a seed — see
 // seed-approval-demo.ts).
 registerShowcaseApprovalDemo(ctx as Parameters<typeof registerShowcaseApprovalDemo>[0]);
 // Hand the nightly health-sweep job its data handle. A job handler is invoked
 // by the job service with `{ jobId, data }` and no engine (flow functions are
 // pure by default, #4396), so `onEnable` — the one place the app is handed a
 // live engine — is where the sweep gets one.
 bindShowcaseJobRuntime(ctx as Parameters<typeof bindShowcaseJobRuntime>[0]);
 // ⛔ Nothing here hands the nightly health-sweep job a data handle any more
 // (#14257). It takes `ql` and `logger` off its own `JobHandlerContext`
 // argument (#14094) — the only route that survives an artifact-served boot,
 // which carries no `onEnable` at all. See `src/automation/jobs/`.
};

2 changes: 1 addition & 1 deletion
examples/app-showcase/src/automation/jobs/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

import { defineJob } from '@objectstack/spec';

export { sweepProjectHealth, bindShowcaseJobRuntime, healthFor } from './sweep-project-health.js';
export { sweepProjectHealth, healthFor } from './sweep-project-health.js';

/**
 * Nightly job — recompute project health.
Expand Down

103 changes: 43 additions & 60 deletions
examples/app-showcase/src/automation/jobs/sweep-project-health.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -20,22 +20,41 @@
 * "never advertise a capability the runtime doesn't deliver" (AGENTS.md Prime
 * Directive #10) cuts both ways.
 *
 * ## Why the engine handle is captured rather than passed in
 * ## Where the engine comes from — the ARGUMENT, never a module-scope handle
 *
 * A job handler is resolved through the SAME `defineStack({ functions })`
 * registry as a `script` flow node (`collectBundleFunctions` in
 * `@objectstack/runtime`), and the job service invokes it with
 * `{ jobId, data }` — `IJobService`'s `JobHandler` context — plus the `bundle`
 * the AppPlugin adds. There is deliberately no data engine in that context: a
 * flow function is PURE by default, returning a value a later declarative node
 * persists (#4343 / #4396).
 *
 * A background job is the case that contract does not cover — nothing
 * downstream is going to persist for it — so it does its own I/O over a handle
 * captured at `onEnable`, and DECLARES that in the `functions` map with
 * `effect: 'writes'` (#4396). That declaration grants nothing; it tells the
 * platform this callable's writes are not counted by the caller, so a run
 * reports "cannot say" instead of silently claiming it wrote nothing.
 * `@objectstack/runtime`), and a `script` node's context deliberately carries
 * no data engine: a flow function is PURE, returning a value a later
 * declarative node persists (#4343 / #4396).
 *
 * A JOB is the case that contract does not cover — it has no graph, so no node
 * before it reads and none after it persists. Since #14094 the AppPlugin
 * therefore invokes a job's `functions` entry with a `JobHandlerContext`:
 * `{ jobId, data, bundle }` widened with `ql` (the same engine handle
 * `defineStack({ onEnable })` receives) and `logger`. This handler takes both
 * from that argument, which is the only route that survives the shipped
 * deployment path.
 *
 * ⛔ The shape this file used to have — `onEnable` filling a module-scope
 * `let host` the handler read later — does NOT survive a built artifact, and
 * fails silently rather than loudly. `objectstack build` emits `functions` into
 * a sibling runtime module exporting only `{ functions, meta }`; the artifact
 * JSON carries no `onEnable`, and `mergeRuntimeModule`
 * (`packages/runtime/src/load-artifact-bundle.ts`) merges only `functions`. So
 * on an artifact-served boot the binding was never made, the handle stayed
 * `undefined`, and `showcase_health_sweep` fired on schedule, recomputed
 * nothing, and reported a clean run (#14257). The pin against a return is in
 * `test/inert-wirings.test.ts`, which reaches this handler through its
 * `functions` entry — the one thing an artifact carries — with no `onEnable`
 * anywhere in the test.
 *
 * The entry still DECLARES `effect: 'writes'` in the `functions` map (#4396),
 * and taking `ql` from the argument does not change that: the declaration was
 * never about where the handle came from. A job's writes are counted by no
 * caller — there is no downstream declarative node to count them — so
 * undeclared, a run reports having written nothing instead of "cannot say",
 * which is indistinguishable from the broken sweep #4354 exists to detect.
 *
 * ## What it computes
 *
Expand All@@ -56,6 +75,8 @@
 * so a steady-state sweep performs zero updates.
 */

import type { JobHandlerContext } from '@objectstack/runtime';

/** Statuses whose health is still in play. */
const SWEPT_STATUSES = ['active', 'on_hold'] as const;

Expand All@@ -71,36 +92,6 @@ const SYS = { isSystem: true } as const;

type Health = 'green' | 'yellow' | 'red';

interface JobHostEngine {
 find: (object: string, query: unknown, options?: unknown) => Promise<unknown>;
 update: (object: string, data: Record<string, unknown>, options?: unknown) => Promise<unknown>;
}

interface JobHostContext {
 ql: JobHostEngine;
 logger?: {
 info?: (...a: unknown[]) => void;
 warn?: (...a: unknown[]) => void;
 };
}

/**
 * The engine handle the job runs over, captured from the host context at
 * `onEnable`. Module scope is what makes it reachable from a `functions` entry,
 * which the job service calls with no context of its own — the "closed over a
 * client at module scope" shape `effect: 'writes'` exists to declare.
 */
let host: JobHostContext | undefined;

/**
 * Give `sweepProjectHealth` its data handle. Called from `onEnable` in
 * `objectstack.config.ts`, which is the one place the app is handed a live
 * engine. Idempotent — a re-enable simply rebinds.
 */
export function bindShowcaseJobRuntime(ctx: JobHostContext): void {
 host = ctx;
}

/** Normalize the engine's list shape (array, or `{ records }`). */
function rowsOf(result: unknown): Array<Record<string, unknown>> {
 if (Array.isArray(result)) return result as Array<Record<string, unknown>>;
Expand All@@ -120,7 +111,7 @@ function num(value: unknown): number | undefined {

/**
 * The health verdict for one project — exported so the rule is unit-testable
 * without an engine (see `test/job-health-sweep.test.ts`).
 * without an engine (see `test/inert-wirings.test.ts`).
 */
export function healthFor(input: {
 budget?: unknown;
Expand DownExpand Up@@ -148,20 +139,12 @@ export function healthFor(input: {
 *
 * Registered as `functions.sweepProjectHealth` with `effect: 'writes'` and
 * scheduled by `HealthSweepJob` (`0 1 * * *` UTC).
 *
 * `jobId`, `ql` and `logger` all come off the `JobHandlerContext` the AppPlugin
 * builds per run — there is no binding step, so there is no boot path on which
 * this handler can be reached without them.
 */
export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void> {
 const jobId = ctx?.jobId ?? 'showcase_health_sweep';
 if (!host) {
 // Reached only if the job somehow fires before `onEnable` bound the
 // handle. Functional degradation, not a durability one: nothing claimed to
 // be persisted has been lost, and the next scheduled run recomputes
 // everything from scratch (AGENTS.md "Degradation log levels").
 // eslint-disable-next-line no-console
 console.warn(`[showcase] ${jobId}: no engine handle bound yet — skipping this run`);
 return;
 }
 const { ql, logger } = host;

export async function sweepProjectHealth({ jobId, ql, logger }: JobHandlerContext): Promise<void> {
 const projects = rowsOf(
 await ql.find('showcase_project', {
 where: { status: { $in: [...SWEPT_STATUSES] } },
Expand All@@ -171,7 +154,7 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 }),
 );
 if (projects.length === 0) {
 logger?.info?.('[showcase] project health sweep: no in-play projects', { job: jobId });
 logger.info('[showcase] project health sweep: no in-play projects', { job: jobId });
 return;
 }

Expand DownExpand Up@@ -208,15 +191,15 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 await ql.update('showcase_project', { id, health: next }, { context: SYS });
 updated += 1;
 } catch (err) {
 logger?.warn?.('[showcase] project health update failed', {
 logger.warn('[showcase] project health update failed', {
 job: jobId,
 project: id,
 error: err instanceof Error ? err.message : String(err),
 });
 }
 }

 logger?.info?.('[showcase] project health sweep complete', {
 logger.info('[showcase] project health sweep complete', {
 job: jobId,
 scanned: projects.length,
 updated,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument#14459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-musk
merged 4 commits into

from

Sep 2, 2026

+193

−115

 Merged


fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument
#14459
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a9c4726

fix(example-showcase): take the sweep's engine off its JobHandlerCont…


claude Sep 2, 2026
7dfba39

test(example-showcase): pin the sweep on an artifact-shaped boot


claude Sep 2, 2026
6aef81f

Merge remote-tracking branch 'origin/main' into claude/issue-14257-sh…


claude Sep 2, 2026
7988dad

test(example-showcase): stop spelling a repo path in the artifact-boo…


claude Sep 2, 2026

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


28 changes: 18 additions & 10 deletions
examples/app-showcase/objectstack.config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -30,7 +30,7 @@ import { CapabilityMapPage, StartHerePage, ComponentGalleryPage, ProjectWorkspac
import { allFlows } from './src/automation/flows/index.js';
import { allWebhooks } from './src/automation/webhooks/index.js';
import { allHooks } from './src/data/hooks/index.js';
import { allJobs, sweepProjectHealth, bindShowcaseJobRuntime } from './src/automation/jobs/index.js';
import { allJobs, sweepProjectHealth } from './src/automation/jobs/index.js';
import { allEmails } from './src/system/emails/index.js';
import { allBooks } from './src/system/books/index.js';
import { allApis } from './src/system/apis/index.js';
Expand DownExpand Up@@ -220,10 +220,19 @@ export default defineStack({
 // A JOB handler resolves through this same map (`collectBundleFunctions`), so
 // `sweepProjectHealth` — the handler `HealthSweepJob` names — lives here too.
 // It is the case the pure contract does not cover: a nightly sweep has no
 // downstream declarative node to persist for it, so it writes over an engine
 // handle captured at `onEnable`. That is why it is spelled the DECLARED way
 // (#4396) — an undeclared writer is counted as having written nothing, which
 // is indistinguishable from the broken sweep #4354 exists to detect.
 // downstream declarative node to persist for it, so it writes over the `ql`
 // handle on its own `JobHandlerContext` argument (#14094). That is why it is
 // spelled the DECLARED way (#4396) — an undeclared writer is counted as
 // having written nothing, which is indistinguishable from the broken sweep
 // #4354 exists to detect. The declaration is about who counts the writes, not
 // about where the handle comes from, so it stands unchanged now that the
 // handle arrives in the argument.
 //
 // ⛔ It is NOT reached through an `onEnable` binding any more (#14257). This
 // map is the ONLY thing `objectstack build` emits into the runtime module and
 // the only thing `mergeRuntimeModule` merges back, so a handler that needed
 // `onEnable` to have run first was inert on every artifact-served boot — on
 // schedule, silently, reported as a clean run.
 //
 // This entry authored the bare form until #4976, not because the bare form was
 // right but because the declared one could not survive `objectstack build`:
Expand DownExpand Up@@ -292,9 +301,8 @@ export const onEnable = async (ctx: unknown): Promise<void> => {
 // real pending requests land in the inbox (cannot be a seed — see
 // seed-approval-demo.ts).
 registerShowcaseApprovalDemo(ctx as Parameters<typeof registerShowcaseApprovalDemo>[0]);
 // Hand the nightly health-sweep job its data handle. A job handler is invoked
 // by the job service with `{ jobId, data }` and no engine (flow functions are
 // pure by default, #4396), so `onEnable` — the one place the app is handed a
 // live engine — is where the sweep gets one.
 bindShowcaseJobRuntime(ctx as Parameters<typeof bindShowcaseJobRuntime>[0]);
 // ⛔ Nothing here hands the nightly health-sweep job a data handle any more
 // (#14257). It takes `ql` and `logger` off its own `JobHandlerContext`
 // argument (#14094) — the only route that survives an artifact-served boot,
 // which carries no `onEnable` at all. See `src/automation/jobs/`.
};

2 changes: 1 addition & 1 deletion
examples/app-showcase/src/automation/jobs/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

import { defineJob } from '@objectstack/spec';

export { sweepProjectHealth, bindShowcaseJobRuntime, healthFor } from './sweep-project-health.js';
export { sweepProjectHealth, healthFor } from './sweep-project-health.js';

/**
 * Nightly job — recompute project health.
Expand Down

103 changes: 43 additions & 60 deletions
examples/app-showcase/src/automation/jobs/sweep-project-health.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -20,22 +20,41 @@
 * "never advertise a capability the runtime doesn't deliver" (AGENTS.md Prime
 * Directive #10) cuts both ways.
 *
 * ## Why the engine handle is captured rather than passed in
 * ## Where the engine comes from — the ARGUMENT, never a module-scope handle
 *
 * A job handler is resolved through the SAME `defineStack({ functions })`
 * registry as a `script` flow node (`collectBundleFunctions` in
 * `@objectstack/runtime`), and the job service invokes it with
 * `{ jobId, data }` — `IJobService`'s `JobHandler` context — plus the `bundle`
 * the AppPlugin adds. There is deliberately no data engine in that context: a
 * flow function is PURE by default, returning a value a later declarative node
 * persists (#4343 / #4396).
 *
 * A background job is the case that contract does not cover — nothing
 * downstream is going to persist for it — so it does its own I/O over a handle
 * captured at `onEnable`, and DECLARES that in the `functions` map with
 * `effect: 'writes'` (#4396). That declaration grants nothing; it tells the
 * platform this callable's writes are not counted by the caller, so a run
 * reports "cannot say" instead of silently claiming it wrote nothing.
 * `@objectstack/runtime`), and a `script` node's context deliberately carries
 * no data engine: a flow function is PURE, returning a value a later
 * declarative node persists (#4343 / #4396).
 *
 * A JOB is the case that contract does not cover — it has no graph, so no node
 * before it reads and none after it persists. Since #14094 the AppPlugin
 * therefore invokes a job's `functions` entry with a `JobHandlerContext`:
 * `{ jobId, data, bundle }` widened with `ql` (the same engine handle
 * `defineStack({ onEnable })` receives) and `logger`. This handler takes both
 * from that argument, which is the only route that survives the shipped
 * deployment path.
 *
 * ⛔ The shape this file used to have — `onEnable` filling a module-scope
 * `let host` the handler read later — does NOT survive a built artifact, and
 * fails silently rather than loudly. `objectstack build` emits `functions` into
 * a sibling runtime module exporting only `{ functions, meta }`; the artifact
 * JSON carries no `onEnable`, and `mergeRuntimeModule`
 * (`packages/runtime/src/load-artifact-bundle.ts`) merges only `functions`. So
 * on an artifact-served boot the binding was never made, the handle stayed
 * `undefined`, and `showcase_health_sweep` fired on schedule, recomputed
 * nothing, and reported a clean run (#14257). The pin against a return is in
 * `test/inert-wirings.test.ts`, which reaches this handler through its
 * `functions` entry — the one thing an artifact carries — with no `onEnable`
 * anywhere in the test.
 *
 * The entry still DECLARES `effect: 'writes'` in the `functions` map (#4396),
 * and taking `ql` from the argument does not change that: the declaration was
 * never about where the handle came from. A job's writes are counted by no
 * caller — there is no downstream declarative node to count them — so
 * undeclared, a run reports having written nothing instead of "cannot say",
 * which is indistinguishable from the broken sweep #4354 exists to detect.
 *
 * ## What it computes
 *
Expand All@@ -56,6 +75,8 @@
 * so a steady-state sweep performs zero updates.
 */

import type { JobHandlerContext } from '@objectstack/runtime';

/** Statuses whose health is still in play. */
const SWEPT_STATUSES = ['active', 'on_hold'] as const;

Expand All@@ -71,36 +92,6 @@ const SYS = { isSystem: true } as const;

type Health = 'green' | 'yellow' | 'red';

interface JobHostEngine {
 find: (object: string, query: unknown, options?: unknown) => Promise<unknown>;
 update: (object: string, data: Record<string, unknown>, options?: unknown) => Promise<unknown>;
}

interface JobHostContext {
 ql: JobHostEngine;
 logger?: {
 info?: (...a: unknown[]) => void;
 warn?: (...a: unknown[]) => void;
 };
}

/**
 * The engine handle the job runs over, captured from the host context at
 * `onEnable`. Module scope is what makes it reachable from a `functions` entry,
 * which the job service calls with no context of its own — the "closed over a
 * client at module scope" shape `effect: 'writes'` exists to declare.
 */
let host: JobHostContext | undefined;

/**
 * Give `sweepProjectHealth` its data handle. Called from `onEnable` in
 * `objectstack.config.ts`, which is the one place the app is handed a live
 * engine. Idempotent — a re-enable simply rebinds.
 */
export function bindShowcaseJobRuntime(ctx: JobHostContext): void {
 host = ctx;
}

/** Normalize the engine's list shape (array, or `{ records }`). */
function rowsOf(result: unknown): Array<Record<string, unknown>> {
 if (Array.isArray(result)) return result as Array<Record<string, unknown>>;
Expand All@@ -120,7 +111,7 @@ function num(value: unknown): number | undefined {

/**
 * The health verdict for one project — exported so the rule is unit-testable
 * without an engine (see `test/job-health-sweep.test.ts`).
 * without an engine (see `test/inert-wirings.test.ts`).
 */
export function healthFor(input: {
 budget?: unknown;
Expand DownExpand Up@@ -148,20 +139,12 @@ export function healthFor(input: {
 *
 * Registered as `functions.sweepProjectHealth` with `effect: 'writes'` and
 * scheduled by `HealthSweepJob` (`0 1 * * *` UTC).
 *
 * `jobId`, `ql` and `logger` all come off the `JobHandlerContext` the AppPlugin
 * builds per run — there is no binding step, so there is no boot path on which
 * this handler can be reached without them.
 */
export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void> {
 const jobId = ctx?.jobId ?? 'showcase_health_sweep';
 if (!host) {
 // Reached only if the job somehow fires before `onEnable` bound the
 // handle. Functional degradation, not a durability one: nothing claimed to
 // be persisted has been lost, and the next scheduled run recomputes
 // everything from scratch (AGENTS.md "Degradation log levels").
 // eslint-disable-next-line no-console
 console.warn(`[showcase] ${jobId}: no engine handle bound yet — skipping this run`);
 return;
 }
 const { ql, logger } = host;

export async function sweepProjectHealth({ jobId, ql, logger }: JobHandlerContext): Promise<void> {
 const projects = rowsOf(
 await ql.find('showcase_project', {
 where: { status: { $in: [...SWEPT_STATUSES] } },
Expand All@@ -171,7 +154,7 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 }),
 );
 if (projects.length === 0) {
 logger?.info?.('[showcase] project health sweep: no in-play projects', { job: jobId });
 logger.info('[showcase] project health sweep: no in-play projects', { job: jobId });
 return;
 }

Expand DownExpand Up@@ -208,15 +191,15 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 await ql.update('showcase_project', { id, health: next }, { context: SYS });
 updated += 1;
 } catch (err) {
 logger?.warn?.('[showcase] project health update failed', {
 logger.warn('[showcase] project health update failed', {
 job: jobId,
 project: id,
 error: err instanceof Error ? err.message : String(err),
 });
 }
 }

 logger?.info?.('[showcase] project health sweep complete', {
 logger.info('[showcase] project health sweep complete', {
 job: jobId,
 scanned: projects.length,
 updated,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument#14459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-musk
merged 4 commits into

from

Sep 2, 2026

+193

−115

 Merged


fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument
#14459
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a9c4726

fix(example-showcase): take the sweep's engine off its JobHandlerCont…


claude Sep 2, 2026
7dfba39

test(example-showcase): pin the sweep on an artifact-shaped boot


claude Sep 2, 2026
6aef81f

Merge remote-tracking branch 'origin/main' into claude/issue-14257-sh…


claude Sep 2, 2026
7988dad

test(example-showcase): stop spelling a repo path in the artifact-boo…


claude Sep 2, 2026

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


28 changes: 18 additions & 10 deletions
examples/app-showcase/objectstack.config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -30,7 +30,7 @@ import { CapabilityMapPage, StartHerePage, ComponentGalleryPage, ProjectWorkspac
import { allFlows } from './src/automation/flows/index.js';
import { allWebhooks } from './src/automation/webhooks/index.js';
import { allHooks } from './src/data/hooks/index.js';
import { allJobs, sweepProjectHealth, bindShowcaseJobRuntime } from './src/automation/jobs/index.js';
import { allJobs, sweepProjectHealth } from './src/automation/jobs/index.js';
import { allEmails } from './src/system/emails/index.js';
import { allBooks } from './src/system/books/index.js';
import { allApis } from './src/system/apis/index.js';
Expand DownExpand Up@@ -220,10 +220,19 @@ export default defineStack({
 // A JOB handler resolves through this same map (`collectBundleFunctions`), so
 // `sweepProjectHealth` — the handler `HealthSweepJob` names — lives here too.
 // It is the case the pure contract does not cover: a nightly sweep has no
 // downstream declarative node to persist for it, so it writes over an engine
 // handle captured at `onEnable`. That is why it is spelled the DECLARED way
 // (#4396) — an undeclared writer is counted as having written nothing, which
 // is indistinguishable from the broken sweep #4354 exists to detect.
 // downstream declarative node to persist for it, so it writes over the `ql`
 // handle on its own `JobHandlerContext` argument (#14094). That is why it is
 // spelled the DECLARED way (#4396) — an undeclared writer is counted as
 // having written nothing, which is indistinguishable from the broken sweep
 // #4354 exists to detect. The declaration is about who counts the writes, not
 // about where the handle comes from, so it stands unchanged now that the
 // handle arrives in the argument.
 //
 // ⛔ It is NOT reached through an `onEnable` binding any more (#14257). This
 // map is the ONLY thing `objectstack build` emits into the runtime module and
 // the only thing `mergeRuntimeModule` merges back, so a handler that needed
 // `onEnable` to have run first was inert on every artifact-served boot — on
 // schedule, silently, reported as a clean run.
 //
 // This entry authored the bare form until #4976, not because the bare form was
 // right but because the declared one could not survive `objectstack build`:
Expand DownExpand Up@@ -292,9 +301,8 @@ export const onEnable = async (ctx: unknown): Promise<void> => {
 // real pending requests land in the inbox (cannot be a seed — see
 // seed-approval-demo.ts).
 registerShowcaseApprovalDemo(ctx as Parameters<typeof registerShowcaseApprovalDemo>[0]);
 // Hand the nightly health-sweep job its data handle. A job handler is invoked
 // by the job service with `{ jobId, data }` and no engine (flow functions are
 // pure by default, #4396), so `onEnable` — the one place the app is handed a
 // live engine — is where the sweep gets one.
 bindShowcaseJobRuntime(ctx as Parameters<typeof bindShowcaseJobRuntime>[0]);
 // ⛔ Nothing here hands the nightly health-sweep job a data handle any more
 // (#14257). It takes `ql` and `logger` off its own `JobHandlerContext`
 // argument (#14094) — the only route that survives an artifact-served boot,
 // which carries no `onEnable` at all. See `src/automation/jobs/`.
};

2 changes: 1 addition & 1 deletion
examples/app-showcase/src/automation/jobs/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

import { defineJob } from '@objectstack/spec';

export { sweepProjectHealth, bindShowcaseJobRuntime, healthFor } from './sweep-project-health.js';
export { sweepProjectHealth, healthFor } from './sweep-project-health.js';

/**
 * Nightly job — recompute project health.
Expand Down

103 changes: 43 additions & 60 deletions
examples/app-showcase/src/automation/jobs/sweep-project-health.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -20,22 +20,41 @@
 * "never advertise a capability the runtime doesn't deliver" (AGENTS.md Prime
 * Directive #10) cuts both ways.
 *
 * ## Why the engine handle is captured rather than passed in
 * ## Where the engine comes from — the ARGUMENT, never a module-scope handle
 *
 * A job handler is resolved through the SAME `defineStack({ functions })`
 * registry as a `script` flow node (`collectBundleFunctions` in
 * `@objectstack/runtime`), and the job service invokes it with
 * `{ jobId, data }` — `IJobService`'s `JobHandler` context — plus the `bundle`
 * the AppPlugin adds. There is deliberately no data engine in that context: a
 * flow function is PURE by default, returning a value a later declarative node
 * persists (#4343 / #4396).
 *
 * A background job is the case that contract does not cover — nothing
 * downstream is going to persist for it — so it does its own I/O over a handle
 * captured at `onEnable`, and DECLARES that in the `functions` map with
 * `effect: 'writes'` (#4396). That declaration grants nothing; it tells the
 * platform this callable's writes are not counted by the caller, so a run
 * reports "cannot say" instead of silently claiming it wrote nothing.
 * `@objectstack/runtime`), and a `script` node's context deliberately carries
 * no data engine: a flow function is PURE, returning a value a later
 * declarative node persists (#4343 / #4396).
 *
 * A JOB is the case that contract does not cover — it has no graph, so no node
 * before it reads and none after it persists. Since #14094 the AppPlugin
 * therefore invokes a job's `functions` entry with a `JobHandlerContext`:
 * `{ jobId, data, bundle }` widened with `ql` (the same engine handle
 * `defineStack({ onEnable })` receives) and `logger`. This handler takes both
 * from that argument, which is the only route that survives the shipped
 * deployment path.
 *
 * ⛔ The shape this file used to have — `onEnable` filling a module-scope
 * `let host` the handler read later — does NOT survive a built artifact, and
 * fails silently rather than loudly. `objectstack build` emits `functions` into
 * a sibling runtime module exporting only `{ functions, meta }`; the artifact
 * JSON carries no `onEnable`, and `mergeRuntimeModule`
 * (`packages/runtime/src/load-artifact-bundle.ts`) merges only `functions`. So
 * on an artifact-served boot the binding was never made, the handle stayed
 * `undefined`, and `showcase_health_sweep` fired on schedule, recomputed
 * nothing, and reported a clean run (#14257). The pin against a return is in
 * `test/inert-wirings.test.ts`, which reaches this handler through its
 * `functions` entry — the one thing an artifact carries — with no `onEnable`
 * anywhere in the test.
 *
 * The entry still DECLARES `effect: 'writes'` in the `functions` map (#4396),
 * and taking `ql` from the argument does not change that: the declaration was
 * never about where the handle came from. A job's writes are counted by no
 * caller — there is no downstream declarative node to count them — so
 * undeclared, a run reports having written nothing instead of "cannot say",
 * which is indistinguishable from the broken sweep #4354 exists to detect.
 *
 * ## What it computes
 *
Expand All@@ -56,6 +75,8 @@
 * so a steady-state sweep performs zero updates.
 */

import type { JobHandlerContext } from '@objectstack/runtime';

/** Statuses whose health is still in play. */
const SWEPT_STATUSES = ['active', 'on_hold'] as const;

Expand All@@ -71,36 +92,6 @@ const SYS = { isSystem: true } as const;

type Health = 'green' | 'yellow' | 'red';

interface JobHostEngine {
 find: (object: string, query: unknown, options?: unknown) => Promise<unknown>;
 update: (object: string, data: Record<string, unknown>, options?: unknown) => Promise<unknown>;
}

interface JobHostContext {
 ql: JobHostEngine;
 logger?: {
 info?: (...a: unknown[]) => void;
 warn?: (...a: unknown[]) => void;
 };
}

/**
 * The engine handle the job runs over, captured from the host context at
 * `onEnable`. Module scope is what makes it reachable from a `functions` entry,
 * which the job service calls with no context of its own — the "closed over a
 * client at module scope" shape `effect: 'writes'` exists to declare.
 */
let host: JobHostContext | undefined;

/**
 * Give `sweepProjectHealth` its data handle. Called from `onEnable` in
 * `objectstack.config.ts`, which is the one place the app is handed a live
 * engine. Idempotent — a re-enable simply rebinds.
 */
export function bindShowcaseJobRuntime(ctx: JobHostContext): void {
 host = ctx;
}

/** Normalize the engine's list shape (array, or `{ records }`). */
function rowsOf(result: unknown): Array<Record<string, unknown>> {
 if (Array.isArray(result)) return result as Array<Record<string, unknown>>;
Expand All@@ -120,7 +111,7 @@ function num(value: unknown): number | undefined {

/**
 * The health verdict for one project — exported so the rule is unit-testable
 * without an engine (see `test/job-health-sweep.test.ts`).
 * without an engine (see `test/inert-wirings.test.ts`).
 */
export function healthFor(input: {
 budget?: unknown;
Expand DownExpand Up@@ -148,20 +139,12 @@ export function healthFor(input: {
 *
 * Registered as `functions.sweepProjectHealth` with `effect: 'writes'` and
 * scheduled by `HealthSweepJob` (`0 1 * * *` UTC).
 *
 * `jobId`, `ql` and `logger` all come off the `JobHandlerContext` the AppPlugin
 * builds per run — there is no binding step, so there is no boot path on which
 * this handler can be reached without them.
 */
export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void> {
 const jobId = ctx?.jobId ?? 'showcase_health_sweep';
 if (!host) {
 // Reached only if the job somehow fires before `onEnable` bound the
 // handle. Functional degradation, not a durability one: nothing claimed to
 // be persisted has been lost, and the next scheduled run recomputes
 // everything from scratch (AGENTS.md "Degradation log levels").
 // eslint-disable-next-line no-console
 console.warn(`[showcase] ${jobId}: no engine handle bound yet — skipping this run`);
 return;
 }
 const { ql, logger } = host;

export async function sweepProjectHealth({ jobId, ql, logger }: JobHandlerContext): Promise<void> {
 const projects = rowsOf(
 await ql.find('showcase_project', {
 where: { status: { $in: [...SWEPT_STATUSES] } },
Expand All@@ -171,7 +154,7 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 }),
 );
 if (projects.length === 0) {
 logger?.info?.('[showcase] project health sweep: no in-play projects', { job: jobId });
 logger.info('[showcase] project health sweep: no in-play projects', { job: jobId });
 return;
 }

Expand DownExpand Up@@ -208,15 +191,15 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 await ql.update('showcase_project', { id, health: next }, { context: SYS });
 updated += 1;
 } catch (err) {
 logger?.warn?.('[showcase] project health update failed', {
 logger.warn('[showcase] project health update failed', {
 job: jobId,
 project: id,
 error: err instanceof Error ? err.message : String(err),
 });
 }
 }

 logger?.info?.('[showcase] project health sweep complete', {
 logger.info('[showcase] project health sweep complete', {
 job: jobId,
 scanned: projects.length,
 updated,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument#14459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-musk
merged 4 commits into

from

Sep 2, 2026

+193

−115

 Merged


fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument
#14459
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a9c4726

fix(example-showcase): take the sweep's engine off its JobHandlerCont…


claude Sep 2, 2026
7dfba39

test(example-showcase): pin the sweep on an artifact-shaped boot


claude Sep 2, 2026
6aef81f

Merge remote-tracking branch 'origin/main' into claude/issue-14257-sh…


claude Sep 2, 2026
7988dad

test(example-showcase): stop spelling a repo path in the artifact-boo…


claude Sep 2, 2026

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


28 changes: 18 additions & 10 deletions
examples/app-showcase/objectstack.config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -30,7 +30,7 @@ import { CapabilityMapPage, StartHerePage, ComponentGalleryPage, ProjectWorkspac
import { allFlows } from './src/automation/flows/index.js';
import { allWebhooks } from './src/automation/webhooks/index.js';
import { allHooks } from './src/data/hooks/index.js';
import { allJobs, sweepProjectHealth, bindShowcaseJobRuntime } from './src/automation/jobs/index.js';
import { allJobs, sweepProjectHealth } from './src/automation/jobs/index.js';
import { allEmails } from './src/system/emails/index.js';
import { allBooks } from './src/system/books/index.js';
import { allApis } from './src/system/apis/index.js';
Expand DownExpand Up@@ -220,10 +220,19 @@ export default defineStack({
 // A JOB handler resolves through this same map (`collectBundleFunctions`), so
 // `sweepProjectHealth` — the handler `HealthSweepJob` names — lives here too.
 // It is the case the pure contract does not cover: a nightly sweep has no
 // downstream declarative node to persist for it, so it writes over an engine
 // handle captured at `onEnable`. That is why it is spelled the DECLARED way
 // (#4396) — an undeclared writer is counted as having written nothing, which
 // is indistinguishable from the broken sweep #4354 exists to detect.
 // downstream declarative node to persist for it, so it writes over the `ql`
 // handle on its own `JobHandlerContext` argument (#14094). That is why it is
 // spelled the DECLARED way (#4396) — an undeclared writer is counted as
 // having written nothing, which is indistinguishable from the broken sweep
 // #4354 exists to detect. The declaration is about who counts the writes, not
 // about where the handle comes from, so it stands unchanged now that the
 // handle arrives in the argument.
 //
 // ⛔ It is NOT reached through an `onEnable` binding any more (#14257). This
 // map is the ONLY thing `objectstack build` emits into the runtime module and
 // the only thing `mergeRuntimeModule` merges back, so a handler that needed
 // `onEnable` to have run first was inert on every artifact-served boot — on
 // schedule, silently, reported as a clean run.
 //
 // This entry authored the bare form until #4976, not because the bare form was
 // right but because the declared one could not survive `objectstack build`:
Expand DownExpand Up@@ -292,9 +301,8 @@ export const onEnable = async (ctx: unknown): Promise<void> => {
 // real pending requests land in the inbox (cannot be a seed — see
 // seed-approval-demo.ts).
 registerShowcaseApprovalDemo(ctx as Parameters<typeof registerShowcaseApprovalDemo>[0]);
 // Hand the nightly health-sweep job its data handle. A job handler is invoked
 // by the job service with `{ jobId, data }` and no engine (flow functions are
 // pure by default, #4396), so `onEnable` — the one place the app is handed a
 // live engine — is where the sweep gets one.
 bindShowcaseJobRuntime(ctx as Parameters<typeof bindShowcaseJobRuntime>[0]);
 // ⛔ Nothing here hands the nightly health-sweep job a data handle any more
 // (#14257). It takes `ql` and `logger` off its own `JobHandlerContext`
 // argument (#14094) — the only route that survives an artifact-served boot,
 // which carries no `onEnable` at all. See `src/automation/jobs/`.
};

2 changes: 1 addition & 1 deletion
examples/app-showcase/src/automation/jobs/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

import { defineJob } from '@objectstack/spec';

export { sweepProjectHealth, bindShowcaseJobRuntime, healthFor } from './sweep-project-health.js';
export { sweepProjectHealth, healthFor } from './sweep-project-health.js';

/**
 * Nightly job — recompute project health.
Expand Down

103 changes: 43 additions & 60 deletions
examples/app-showcase/src/automation/jobs/sweep-project-health.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -20,22 +20,41 @@
 * "never advertise a capability the runtime doesn't deliver" (AGENTS.md Prime
 * Directive #10) cuts both ways.
 *
 * ## Why the engine handle is captured rather than passed in
 * ## Where the engine comes from — the ARGUMENT, never a module-scope handle
 *
 * A job handler is resolved through the SAME `defineStack({ functions })`
 * registry as a `script` flow node (`collectBundleFunctions` in
 * `@objectstack/runtime`), and the job service invokes it with
 * `{ jobId, data }` — `IJobService`'s `JobHandler` context — plus the `bundle`
 * the AppPlugin adds. There is deliberately no data engine in that context: a
 * flow function is PURE by default, returning a value a later declarative node
 * persists (#4343 / #4396).
 *
 * A background job is the case that contract does not cover — nothing
 * downstream is going to persist for it — so it does its own I/O over a handle
 * captured at `onEnable`, and DECLARES that in the `functions` map with
 * `effect: 'writes'` (#4396). That declaration grants nothing; it tells the
 * platform this callable's writes are not counted by the caller, so a run
 * reports "cannot say" instead of silently claiming it wrote nothing.
 * `@objectstack/runtime`), and a `script` node's context deliberately carries
 * no data engine: a flow function is PURE, returning a value a later
 * declarative node persists (#4343 / #4396).
 *
 * A JOB is the case that contract does not cover — it has no graph, so no node
 * before it reads and none after it persists. Since #14094 the AppPlugin
 * therefore invokes a job's `functions` entry with a `JobHandlerContext`:
 * `{ jobId, data, bundle }` widened with `ql` (the same engine handle
 * `defineStack({ onEnable })` receives) and `logger`. This handler takes both
 * from that argument, which is the only route that survives the shipped
 * deployment path.
 *
 * ⛔ The shape this file used to have — `onEnable` filling a module-scope
 * `let host` the handler read later — does NOT survive a built artifact, and
 * fails silently rather than loudly. `objectstack build` emits `functions` into
 * a sibling runtime module exporting only `{ functions, meta }`; the artifact
 * JSON carries no `onEnable`, and `mergeRuntimeModule`
 * (`packages/runtime/src/load-artifact-bundle.ts`) merges only `functions`. So
 * on an artifact-served boot the binding was never made, the handle stayed
 * `undefined`, and `showcase_health_sweep` fired on schedule, recomputed
 * nothing, and reported a clean run (#14257). The pin against a return is in
 * `test/inert-wirings.test.ts`, which reaches this handler through its
 * `functions` entry — the one thing an artifact carries — with no `onEnable`
 * anywhere in the test.
 *
 * The entry still DECLARES `effect: 'writes'` in the `functions` map (#4396),
 * and taking `ql` from the argument does not change that: the declaration was
 * never about where the handle came from. A job's writes are counted by no
 * caller — there is no downstream declarative node to count them — so
 * undeclared, a run reports having written nothing instead of "cannot say",
 * which is indistinguishable from the broken sweep #4354 exists to detect.
 *
 * ## What it computes
 *
Expand All@@ -56,6 +75,8 @@
 * so a steady-state sweep performs zero updates.
 */

import type { JobHandlerContext } from '@objectstack/runtime';

/** Statuses whose health is still in play. */
const SWEPT_STATUSES = ['active', 'on_hold'] as const;

Expand All@@ -71,36 +92,6 @@ const SYS = { isSystem: true } as const;

type Health = 'green' | 'yellow' | 'red';

interface JobHostEngine {
 find: (object: string, query: unknown, options?: unknown) => Promise<unknown>;
 update: (object: string, data: Record<string, unknown>, options?: unknown) => Promise<unknown>;
}

interface JobHostContext {
 ql: JobHostEngine;
 logger?: {
 info?: (...a: unknown[]) => void;
 warn?: (...a: unknown[]) => void;
 };
}

/**
 * The engine handle the job runs over, captured from the host context at
 * `onEnable`. Module scope is what makes it reachable from a `functions` entry,
 * which the job service calls with no context of its own — the "closed over a
 * client at module scope" shape `effect: 'writes'` exists to declare.
 */
let host: JobHostContext | undefined;

/**
 * Give `sweepProjectHealth` its data handle. Called from `onEnable` in
 * `objectstack.config.ts`, which is the one place the app is handed a live
 * engine. Idempotent — a re-enable simply rebinds.
 */
export function bindShowcaseJobRuntime(ctx: JobHostContext): void {
 host = ctx;
}

/** Normalize the engine's list shape (array, or `{ records }`). */
function rowsOf(result: unknown): Array<Record<string, unknown>> {
 if (Array.isArray(result)) return result as Array<Record<string, unknown>>;
Expand All@@ -120,7 +111,7 @@ function num(value: unknown): number | undefined {

/**
 * The health verdict for one project — exported so the rule is unit-testable
 * without an engine (see `test/job-health-sweep.test.ts`).
 * without an engine (see `test/inert-wirings.test.ts`).
 */
export function healthFor(input: {
 budget?: unknown;
Expand DownExpand Up@@ -148,20 +139,12 @@ export function healthFor(input: {
 *
 * Registered as `functions.sweepProjectHealth` with `effect: 'writes'` and
 * scheduled by `HealthSweepJob` (`0 1 * * *` UTC).
 *
 * `jobId`, `ql` and `logger` all come off the `JobHandlerContext` the AppPlugin
 * builds per run — there is no binding step, so there is no boot path on which
 * this handler can be reached without them.
 */
export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void> {
 const jobId = ctx?.jobId ?? 'showcase_health_sweep';
 if (!host) {
 // Reached only if the job somehow fires before `onEnable` bound the
 // handle. Functional degradation, not a durability one: nothing claimed to
 // be persisted has been lost, and the next scheduled run recomputes
 // everything from scratch (AGENTS.md "Degradation log levels").
 // eslint-disable-next-line no-console
 console.warn(`[showcase] ${jobId}: no engine handle bound yet — skipping this run`);
 return;
 }
 const { ql, logger } = host;

export async function sweepProjectHealth({ jobId, ql, logger }: JobHandlerContext): Promise<void> {
 const projects = rowsOf(
 await ql.find('showcase_project', {
 where: { status: { $in: [...SWEPT_STATUSES] } },
Expand All@@ -171,7 +154,7 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 }),
 );
 if (projects.length === 0) {
 logger?.info?.('[showcase] project health sweep: no in-play projects', { job: jobId });
 logger.info('[showcase] project health sweep: no in-play projects', { job: jobId });
 return;
 }

Expand DownExpand Up@@ -208,15 +191,15 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 await ql.update('showcase_project', { id, health: next }, { context: SYS });
 updated += 1;
 } catch (err) {
 logger?.warn?.('[showcase] project health update failed', {
 logger.warn('[showcase] project health update failed', {
 job: jobId,
 project: id,
 error: err instanceof Error ? err.message : String(err),
 });
 }
 }

 logger?.info?.('[showcase] project health sweep complete', {
 logger.info('[showcase] project health sweep complete', {
 job: jobId,
 scanned: projects.length,
 updated,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument#14459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-musk
merged 4 commits into

from

Sep 2, 2026

+193

−115

 Merged


fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument
#14459
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a9c4726

fix(example-showcase): take the sweep's engine off its JobHandlerCont…


claude Sep 2, 2026
7dfba39

test(example-showcase): pin the sweep on an artifact-shaped boot


claude Sep 2, 2026
6aef81f

Merge remote-tracking branch 'origin/main' into claude/issue-14257-sh…


claude Sep 2, 2026
7988dad

test(example-showcase): stop spelling a repo path in the artifact-boo…


claude Sep 2, 2026

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


28 changes: 18 additions & 10 deletions
examples/app-showcase/objectstack.config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -30,7 +30,7 @@ import { CapabilityMapPage, StartHerePage, ComponentGalleryPage, ProjectWorkspac
import { allFlows } from './src/automation/flows/index.js';
import { allWebhooks } from './src/automation/webhooks/index.js';
import { allHooks } from './src/data/hooks/index.js';
import { allJobs, sweepProjectHealth, bindShowcaseJobRuntime } from './src/automation/jobs/index.js';
import { allJobs, sweepProjectHealth } from './src/automation/jobs/index.js';
import { allEmails } from './src/system/emails/index.js';
import { allBooks } from './src/system/books/index.js';
import { allApis } from './src/system/apis/index.js';
Expand DownExpand Up@@ -220,10 +220,19 @@ export default defineStack({
 // A JOB handler resolves through this same map (`collectBundleFunctions`), so
 // `sweepProjectHealth` — the handler `HealthSweepJob` names — lives here too.
 // It is the case the pure contract does not cover: a nightly sweep has no
 // downstream declarative node to persist for it, so it writes over an engine
 // handle captured at `onEnable`. That is why it is spelled the DECLARED way
 // (#4396) — an undeclared writer is counted as having written nothing, which
 // is indistinguishable from the broken sweep #4354 exists to detect.
 // downstream declarative node to persist for it, so it writes over the `ql`
 // handle on its own `JobHandlerContext` argument (#14094). That is why it is
 // spelled the DECLARED way (#4396) — an undeclared writer is counted as
 // having written nothing, which is indistinguishable from the broken sweep
 // #4354 exists to detect. The declaration is about who counts the writes, not
 // about where the handle comes from, so it stands unchanged now that the
 // handle arrives in the argument.
 //
 // ⛔ It is NOT reached through an `onEnable` binding any more (#14257). This
 // map is the ONLY thing `objectstack build` emits into the runtime module and
 // the only thing `mergeRuntimeModule` merges back, so a handler that needed
 // `onEnable` to have run first was inert on every artifact-served boot — on
 // schedule, silently, reported as a clean run.
 //
 // This entry authored the bare form until #4976, not because the bare form was
 // right but because the declared one could not survive `objectstack build`:
Expand DownExpand Up@@ -292,9 +301,8 @@ export const onEnable = async (ctx: unknown): Promise<void> => {
 // real pending requests land in the inbox (cannot be a seed — see
 // seed-approval-demo.ts).
 registerShowcaseApprovalDemo(ctx as Parameters<typeof registerShowcaseApprovalDemo>[0]);
 // Hand the nightly health-sweep job its data handle. A job handler is invoked
 // by the job service with `{ jobId, data }` and no engine (flow functions are
 // pure by default, #4396), so `onEnable` — the one place the app is handed a
 // live engine — is where the sweep gets one.
 bindShowcaseJobRuntime(ctx as Parameters<typeof bindShowcaseJobRuntime>[0]);
 // ⛔ Nothing here hands the nightly health-sweep job a data handle any more
 // (#14257). It takes `ql` and `logger` off its own `JobHandlerContext`
 // argument (#14094) — the only route that survives an artifact-served boot,
 // which carries no `onEnable` at all. See `src/automation/jobs/`.
};

2 changes: 1 addition & 1 deletion
examples/app-showcase/src/automation/jobs/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

import { defineJob } from '@objectstack/spec';

export { sweepProjectHealth, bindShowcaseJobRuntime, healthFor } from './sweep-project-health.js';
export { sweepProjectHealth, healthFor } from './sweep-project-health.js';

/**
 * Nightly job — recompute project health.
Expand Down

103 changes: 43 additions & 60 deletions
examples/app-showcase/src/automation/jobs/sweep-project-health.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -20,22 +20,41 @@
 * "never advertise a capability the runtime doesn't deliver" (AGENTS.md Prime
 * Directive #10) cuts both ways.
 *
 * ## Why the engine handle is captured rather than passed in
 * ## Where the engine comes from — the ARGUMENT, never a module-scope handle
 *
 * A job handler is resolved through the SAME `defineStack({ functions })`
 * registry as a `script` flow node (`collectBundleFunctions` in
 * `@objectstack/runtime`), and the job service invokes it with
 * `{ jobId, data }` — `IJobService`'s `JobHandler` context — plus the `bundle`
 * the AppPlugin adds. There is deliberately no data engine in that context: a
 * flow function is PURE by default, returning a value a later declarative node
 * persists (#4343 / #4396).
 *
 * A background job is the case that contract does not cover — nothing
 * downstream is going to persist for it — so it does its own I/O over a handle
 * captured at `onEnable`, and DECLARES that in the `functions` map with
 * `effect: 'writes'` (#4396). That declaration grants nothing; it tells the
 * platform this callable's writes are not counted by the caller, so a run
 * reports "cannot say" instead of silently claiming it wrote nothing.
 * `@objectstack/runtime`), and a `script` node's context deliberately carries
 * no data engine: a flow function is PURE, returning a value a later
 * declarative node persists (#4343 / #4396).
 *
 * A JOB is the case that contract does not cover — it has no graph, so no node
 * before it reads and none after it persists. Since #14094 the AppPlugin
 * therefore invokes a job's `functions` entry with a `JobHandlerContext`:
 * `{ jobId, data, bundle }` widened with `ql` (the same engine handle
 * `defineStack({ onEnable })` receives) and `logger`. This handler takes both
 * from that argument, which is the only route that survives the shipped
 * deployment path.
 *
 * ⛔ The shape this file used to have — `onEnable` filling a module-scope
 * `let host` the handler read later — does NOT survive a built artifact, and
 * fails silently rather than loudly. `objectstack build` emits `functions` into
 * a sibling runtime module exporting only `{ functions, meta }`; the artifact
 * JSON carries no `onEnable`, and `mergeRuntimeModule`
 * (`packages/runtime/src/load-artifact-bundle.ts`) merges only `functions`. So
 * on an artifact-served boot the binding was never made, the handle stayed
 * `undefined`, and `showcase_health_sweep` fired on schedule, recomputed
 * nothing, and reported a clean run (#14257). The pin against a return is in
 * `test/inert-wirings.test.ts`, which reaches this handler through its
 * `functions` entry — the one thing an artifact carries — with no `onEnable`
 * anywhere in the test.
 *
 * The entry still DECLARES `effect: 'writes'` in the `functions` map (#4396),
 * and taking `ql` from the argument does not change that: the declaration was
 * never about where the handle came from. A job's writes are counted by no
 * caller — there is no downstream declarative node to count them — so
 * undeclared, a run reports having written nothing instead of "cannot say",
 * which is indistinguishable from the broken sweep #4354 exists to detect.
 *
 * ## What it computes
 *
Expand All@@ -56,6 +75,8 @@
 * so a steady-state sweep performs zero updates.
 */

import type { JobHandlerContext } from '@objectstack/runtime';

/** Statuses whose health is still in play. */
const SWEPT_STATUSES = ['active', 'on_hold'] as const;

Expand All@@ -71,36 +92,6 @@ const SYS = { isSystem: true } as const;

type Health = 'green' | 'yellow' | 'red';

interface JobHostEngine {
 find: (object: string, query: unknown, options?: unknown) => Promise<unknown>;
 update: (object: string, data: Record<string, unknown>, options?: unknown) => Promise<unknown>;
}

interface JobHostContext {
 ql: JobHostEngine;
 logger?: {
 info?: (...a: unknown[]) => void;
 warn?: (...a: unknown[]) => void;
 };
}

/**
 * The engine handle the job runs over, captured from the host context at
 * `onEnable`. Module scope is what makes it reachable from a `functions` entry,
 * which the job service calls with no context of its own — the "closed over a
 * client at module scope" shape `effect: 'writes'` exists to declare.
 */
let host: JobHostContext | undefined;

/**
 * Give `sweepProjectHealth` its data handle. Called from `onEnable` in
 * `objectstack.config.ts`, which is the one place the app is handed a live
 * engine. Idempotent — a re-enable simply rebinds.
 */
export function bindShowcaseJobRuntime(ctx: JobHostContext): void {
 host = ctx;
}

/** Normalize the engine's list shape (array, or `{ records }`). */
function rowsOf(result: unknown): Array<Record<string, unknown>> {
 if (Array.isArray(result)) return result as Array<Record<string, unknown>>;
Expand All@@ -120,7 +111,7 @@ function num(value: unknown): number | undefined {

/**
 * The health verdict for one project — exported so the rule is unit-testable
 * without an engine (see `test/job-health-sweep.test.ts`).
 * without an engine (see `test/inert-wirings.test.ts`).
 */
export function healthFor(input: {
 budget?: unknown;
Expand DownExpand Up@@ -148,20 +139,12 @@ export function healthFor(input: {
 *
 * Registered as `functions.sweepProjectHealth` with `effect: 'writes'` and
 * scheduled by `HealthSweepJob` (`0 1 * * *` UTC).
 *
 * `jobId`, `ql` and `logger` all come off the `JobHandlerContext` the AppPlugin
 * builds per run — there is no binding step, so there is no boot path on which
 * this handler can be reached without them.
 */
export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void> {
 const jobId = ctx?.jobId ?? 'showcase_health_sweep';
 if (!host) {
 // Reached only if the job somehow fires before `onEnable` bound the
 // handle. Functional degradation, not a durability one: nothing claimed to
 // be persisted has been lost, and the next scheduled run recomputes
 // everything from scratch (AGENTS.md "Degradation log levels").
 // eslint-disable-next-line no-console
 console.warn(`[showcase] ${jobId}: no engine handle bound yet — skipping this run`);
 return;
 }
 const { ql, logger } = host;

export async function sweepProjectHealth({ jobId, ql, logger }: JobHandlerContext): Promise<void> {
 const projects = rowsOf(
 await ql.find('showcase_project', {
 where: { status: { $in: [...SWEPT_STATUSES] } },
Expand All@@ -171,7 +154,7 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 }),
 );
 if (projects.length === 0) {
 logger?.info?.('[showcase] project health sweep: no in-play projects', { job: jobId });
 logger.info('[showcase] project health sweep: no in-play projects', { job: jobId });
 return;
 }

Expand DownExpand Up@@ -208,15 +191,15 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 await ql.update('showcase_project', { id, health: next }, { context: SYS });
 updated += 1;
 } catch (err) {
 logger?.warn?.('[showcase] project health update failed', {
 logger.warn('[showcase] project health update failed', {
 job: jobId,
 project: id,
 error: err instanceof Error ? err.message : String(err),
 });
 }
 }

 logger?.info?.('[showcase] project health sweep complete', {
 logger.info('[showcase] project health sweep complete', {
 job: jobId,
 scanned: projects.length,
 updated,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument#14459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-musk
merged 4 commits into

from

Sep 2, 2026

+193

−115

 Merged


fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument
#14459
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a9c4726

fix(example-showcase): take the sweep's engine off its JobHandlerCont…


claude Sep 2, 2026
7dfba39

test(example-showcase): pin the sweep on an artifact-shaped boot


claude Sep 2, 2026
6aef81f

Merge remote-tracking branch 'origin/main' into claude/issue-14257-sh…


claude Sep 2, 2026
7988dad

test(example-showcase): stop spelling a repo path in the artifact-boo…


claude Sep 2, 2026

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


28 changes: 18 additions & 10 deletions
examples/app-showcase/objectstack.config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -30,7 +30,7 @@ import { CapabilityMapPage, StartHerePage, ComponentGalleryPage, ProjectWorkspac
import { allFlows } from './src/automation/flows/index.js';
import { allWebhooks } from './src/automation/webhooks/index.js';
import { allHooks } from './src/data/hooks/index.js';
import { allJobs, sweepProjectHealth, bindShowcaseJobRuntime } from './src/automation/jobs/index.js';
import { allJobs, sweepProjectHealth } from './src/automation/jobs/index.js';
import { allEmails } from './src/system/emails/index.js';
import { allBooks } from './src/system/books/index.js';
import { allApis } from './src/system/apis/index.js';
Expand DownExpand Up@@ -220,10 +220,19 @@ export default defineStack({
 // A JOB handler resolves through this same map (`collectBundleFunctions`), so
 // `sweepProjectHealth` — the handler `HealthSweepJob` names — lives here too.
 // It is the case the pure contract does not cover: a nightly sweep has no
 // downstream declarative node to persist for it, so it writes over an engine
 // handle captured at `onEnable`. That is why it is spelled the DECLARED way
 // (#4396) — an undeclared writer is counted as having written nothing, which
 // is indistinguishable from the broken sweep #4354 exists to detect.
 // downstream declarative node to persist for it, so it writes over the `ql`
 // handle on its own `JobHandlerContext` argument (#14094). That is why it is
 // spelled the DECLARED way (#4396) — an undeclared writer is counted as
 // having written nothing, which is indistinguishable from the broken sweep
 // #4354 exists to detect. The declaration is about who counts the writes, not
 // about where the handle comes from, so it stands unchanged now that the
 // handle arrives in the argument.
 //
 // ⛔ It is NOT reached through an `onEnable` binding any more (#14257). This
 // map is the ONLY thing `objectstack build` emits into the runtime module and
 // the only thing `mergeRuntimeModule` merges back, so a handler that needed
 // `onEnable` to have run first was inert on every artifact-served boot — on
 // schedule, silently, reported as a clean run.
 //
 // This entry authored the bare form until #4976, not because the bare form was
 // right but because the declared one could not survive `objectstack build`:
Expand DownExpand Up@@ -292,9 +301,8 @@ export const onEnable = async (ctx: unknown): Promise<void> => {
 // real pending requests land in the inbox (cannot be a seed — see
 // seed-approval-demo.ts).
 registerShowcaseApprovalDemo(ctx as Parameters<typeof registerShowcaseApprovalDemo>[0]);
 // Hand the nightly health-sweep job its data handle. A job handler is invoked
 // by the job service with `{ jobId, data }` and no engine (flow functions are
 // pure by default, #4396), so `onEnable` — the one place the app is handed a
 // live engine — is where the sweep gets one.
 bindShowcaseJobRuntime(ctx as Parameters<typeof bindShowcaseJobRuntime>[0]);
 // ⛔ Nothing here hands the nightly health-sweep job a data handle any more
 // (#14257). It takes `ql` and `logger` off its own `JobHandlerContext`
 // argument (#14094) — the only route that survives an artifact-served boot,
 // which carries no `onEnable` at all. See `src/automation/jobs/`.
};

2 changes: 1 addition & 1 deletion
examples/app-showcase/src/automation/jobs/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

import { defineJob } from '@objectstack/spec';

export { sweepProjectHealth, bindShowcaseJobRuntime, healthFor } from './sweep-project-health.js';
export { sweepProjectHealth, healthFor } from './sweep-project-health.js';

/**
 * Nightly job — recompute project health.
Expand Down

103 changes: 43 additions & 60 deletions
examples/app-showcase/src/automation/jobs/sweep-project-health.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -20,22 +20,41 @@
 * "never advertise a capability the runtime doesn't deliver" (AGENTS.md Prime
 * Directive #10) cuts both ways.
 *
 * ## Why the engine handle is captured rather than passed in
 * ## Where the engine comes from — the ARGUMENT, never a module-scope handle
 *
 * A job handler is resolved through the SAME `defineStack({ functions })`
 * registry as a `script` flow node (`collectBundleFunctions` in
 * `@objectstack/runtime`), and the job service invokes it with
 * `{ jobId, data }` — `IJobService`'s `JobHandler` context — plus the `bundle`
 * the AppPlugin adds. There is deliberately no data engine in that context: a
 * flow function is PURE by default, returning a value a later declarative node
 * persists (#4343 / #4396).
 *
 * A background job is the case that contract does not cover — nothing
 * downstream is going to persist for it — so it does its own I/O over a handle
 * captured at `onEnable`, and DECLARES that in the `functions` map with
 * `effect: 'writes'` (#4396). That declaration grants nothing; it tells the
 * platform this callable's writes are not counted by the caller, so a run
 * reports "cannot say" instead of silently claiming it wrote nothing.
 * `@objectstack/runtime`), and a `script` node's context deliberately carries
 * no data engine: a flow function is PURE, returning a value a later
 * declarative node persists (#4343 / #4396).
 *
 * A JOB is the case that contract does not cover — it has no graph, so no node
 * before it reads and none after it persists. Since #14094 the AppPlugin
 * therefore invokes a job's `functions` entry with a `JobHandlerContext`:
 * `{ jobId, data, bundle }` widened with `ql` (the same engine handle
 * `defineStack({ onEnable })` receives) and `logger`. This handler takes both
 * from that argument, which is the only route that survives the shipped
 * deployment path.
 *
 * ⛔ The shape this file used to have — `onEnable` filling a module-scope
 * `let host` the handler read later — does NOT survive a built artifact, and
 * fails silently rather than loudly. `objectstack build` emits `functions` into
 * a sibling runtime module exporting only `{ functions, meta }`; the artifact
 * JSON carries no `onEnable`, and `mergeRuntimeModule`
 * (`packages/runtime/src/load-artifact-bundle.ts`) merges only `functions`. So
 * on an artifact-served boot the binding was never made, the handle stayed
 * `undefined`, and `showcase_health_sweep` fired on schedule, recomputed
 * nothing, and reported a clean run (#14257). The pin against a return is in
 * `test/inert-wirings.test.ts`, which reaches this handler through its
 * `functions` entry — the one thing an artifact carries — with no `onEnable`
 * anywhere in the test.
 *
 * The entry still DECLARES `effect: 'writes'` in the `functions` map (#4396),
 * and taking `ql` from the argument does not change that: the declaration was
 * never about where the handle came from. A job's writes are counted by no
 * caller — there is no downstream declarative node to count them — so
 * undeclared, a run reports having written nothing instead of "cannot say",
 * which is indistinguishable from the broken sweep #4354 exists to detect.
 *
 * ## What it computes
 *
Expand All@@ -56,6 +75,8 @@
 * so a steady-state sweep performs zero updates.
 */

import type { JobHandlerContext } from '@objectstack/runtime';

/** Statuses whose health is still in play. */
const SWEPT_STATUSES = ['active', 'on_hold'] as const;

Expand All@@ -71,36 +92,6 @@ const SYS = { isSystem: true } as const;

type Health = 'green' | 'yellow' | 'red';

interface JobHostEngine {
 find: (object: string, query: unknown, options?: unknown) => Promise<unknown>;
 update: (object: string, data: Record<string, unknown>, options?: unknown) => Promise<unknown>;
}

interface JobHostContext {
 ql: JobHostEngine;
 logger?: {
 info?: (...a: unknown[]) => void;
 warn?: (...a: unknown[]) => void;
 };
}

/**
 * The engine handle the job runs over, captured from the host context at
 * `onEnable`. Module scope is what makes it reachable from a `functions` entry,
 * which the job service calls with no context of its own — the "closed over a
 * client at module scope" shape `effect: 'writes'` exists to declare.
 */
let host: JobHostContext | undefined;

/**
 * Give `sweepProjectHealth` its data handle. Called from `onEnable` in
 * `objectstack.config.ts`, which is the one place the app is handed a live
 * engine. Idempotent — a re-enable simply rebinds.
 */
export function bindShowcaseJobRuntime(ctx: JobHostContext): void {
 host = ctx;
}

/** Normalize the engine's list shape (array, or `{ records }`). */
function rowsOf(result: unknown): Array<Record<string, unknown>> {
 if (Array.isArray(result)) return result as Array<Record<string, unknown>>;
Expand All@@ -120,7 +111,7 @@ function num(value: unknown): number | undefined {

/**
 * The health verdict for one project — exported so the rule is unit-testable
 * without an engine (see `test/job-health-sweep.test.ts`).
 * without an engine (see `test/inert-wirings.test.ts`).
 */
export function healthFor(input: {
 budget?: unknown;
Expand DownExpand Up@@ -148,20 +139,12 @@ export function healthFor(input: {
 *
 * Registered as `functions.sweepProjectHealth` with `effect: 'writes'` and
 * scheduled by `HealthSweepJob` (`0 1 * * *` UTC).
 *
 * `jobId`, `ql` and `logger` all come off the `JobHandlerContext` the AppPlugin
 * builds per run — there is no binding step, so there is no boot path on which
 * this handler can be reached without them.
 */
export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void> {
 const jobId = ctx?.jobId ?? 'showcase_health_sweep';
 if (!host) {
 // Reached only if the job somehow fires before `onEnable` bound the
 // handle. Functional degradation, not a durability one: nothing claimed to
 // be persisted has been lost, and the next scheduled run recomputes
 // everything from scratch (AGENTS.md "Degradation log levels").
 // eslint-disable-next-line no-console
 console.warn(`[showcase] ${jobId}: no engine handle bound yet — skipping this run`);
 return;
 }
 const { ql, logger } = host;

export async function sweepProjectHealth({ jobId, ql, logger }: JobHandlerContext): Promise<void> {
 const projects = rowsOf(
 await ql.find('showcase_project', {
 where: { status: { $in: [...SWEPT_STATUSES] } },
Expand All@@ -171,7 +154,7 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 }),
 );
 if (projects.length === 0) {
 logger?.info?.('[showcase] project health sweep: no in-play projects', { job: jobId });
 logger.info('[showcase] project health sweep: no in-play projects', { job: jobId });
 return;
 }

Expand DownExpand Up@@ -208,15 +191,15 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 await ql.update('showcase_project', { id, health: next }, { context: SYS });
 updated += 1;
 } catch (err) {
 logger?.warn?.('[showcase] project health update failed', {
 logger.warn('[showcase] project health update failed', {
 job: jobId,
 project: id,
 error: err instanceof Error ? err.message : String(err),
 });
 }
 }

 logger?.info?.('[showcase] project health sweep complete', {
 logger.info('[showcase] project health sweep complete', {
 job: jobId,
 scanned: projects.length,
 updated,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument#14459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-musk
merged 4 commits into

from

Sep 2, 2026

+193

−115

 Merged


fix(example-showcase): the nightly health sweep takes its engine off the job handler's argument
#14459
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a9c4726

fix(example-showcase): take the sweep's engine off its JobHandlerCont…


claude Sep 2, 2026
7dfba39

test(example-showcase): pin the sweep on an artifact-shaped boot


claude Sep 2, 2026
6aef81f

Merge remote-tracking branch 'origin/main' into claude/issue-14257-sh…


claude Sep 2, 2026
7988dad

test(example-showcase): stop spelling a repo path in the artifact-boo…


claude Sep 2, 2026

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


28 changes: 18 additions & 10 deletions
examples/app-showcase/objectstack.config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -30,7 +30,7 @@ import { CapabilityMapPage, StartHerePage, ComponentGalleryPage, ProjectWorkspac
import { allFlows } from './src/automation/flows/index.js';
import { allWebhooks } from './src/automation/webhooks/index.js';
import { allHooks } from './src/data/hooks/index.js';
import { allJobs, sweepProjectHealth, bindShowcaseJobRuntime } from './src/automation/jobs/index.js';
import { allJobs, sweepProjectHealth } from './src/automation/jobs/index.js';
import { allEmails } from './src/system/emails/index.js';
import { allBooks } from './src/system/books/index.js';
import { allApis } from './src/system/apis/index.js';
Expand DownExpand Up@@ -220,10 +220,19 @@ export default defineStack({
 // A JOB handler resolves through this same map (`collectBundleFunctions`), so
 // `sweepProjectHealth` — the handler `HealthSweepJob` names — lives here too.
 // It is the case the pure contract does not cover: a nightly sweep has no
 // downstream declarative node to persist for it, so it writes over an engine
 // handle captured at `onEnable`. That is why it is spelled the DECLARED way
 // (#4396) — an undeclared writer is counted as having written nothing, which
 // is indistinguishable from the broken sweep #4354 exists to detect.
 // downstream declarative node to persist for it, so it writes over the `ql`
 // handle on its own `JobHandlerContext` argument (#14094). That is why it is
 // spelled the DECLARED way (#4396) — an undeclared writer is counted as
 // having written nothing, which is indistinguishable from the broken sweep
 // #4354 exists to detect. The declaration is about who counts the writes, not
 // about where the handle comes from, so it stands unchanged now that the
 // handle arrives in the argument.
 //
 // ⛔ It is NOT reached through an `onEnable` binding any more (#14257). This
 // map is the ONLY thing `objectstack build` emits into the runtime module and
 // the only thing `mergeRuntimeModule` merges back, so a handler that needed
 // `onEnable` to have run first was inert on every artifact-served boot — on
 // schedule, silently, reported as a clean run.
 //
 // This entry authored the bare form until #4976, not because the bare form was
 // right but because the declared one could not survive `objectstack build`:
Expand DownExpand Up@@ -292,9 +301,8 @@ export const onEnable = async (ctx: unknown): Promise<void> => {
 // real pending requests land in the inbox (cannot be a seed — see
 // seed-approval-demo.ts).
 registerShowcaseApprovalDemo(ctx as Parameters<typeof registerShowcaseApprovalDemo>[0]);
 // Hand the nightly health-sweep job its data handle. A job handler is invoked
 // by the job service with `{ jobId, data }` and no engine (flow functions are
 // pure by default, #4396), so `onEnable` — the one place the app is handed a
 // live engine — is where the sweep gets one.
 bindShowcaseJobRuntime(ctx as Parameters<typeof bindShowcaseJobRuntime>[0]);
 // ⛔ Nothing here hands the nightly health-sweep job a data handle any more
 // (#14257). It takes `ql` and `logger` off its own `JobHandlerContext`
 // argument (#14094) — the only route that survives an artifact-served boot,
 // which carries no `onEnable` at all. See `src/automation/jobs/`.
};

2 changes: 1 addition & 1 deletion
examples/app-showcase/src/automation/jobs/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

import { defineJob } from '@objectstack/spec';

export { sweepProjectHealth, bindShowcaseJobRuntime, healthFor } from './sweep-project-health.js';
export { sweepProjectHealth, healthFor } from './sweep-project-health.js';

/**
 * Nightly job — recompute project health.
Expand Down

103 changes: 43 additions & 60 deletions
examples/app-showcase/src/automation/jobs/sweep-project-health.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -20,22 +20,41 @@
 * "never advertise a capability the runtime doesn't deliver" (AGENTS.md Prime
 * Directive #10) cuts both ways.
 *
 * ## Why the engine handle is captured rather than passed in
 * ## Where the engine comes from — the ARGUMENT, never a module-scope handle
 *
 * A job handler is resolved through the SAME `defineStack({ functions })`
 * registry as a `script` flow node (`collectBundleFunctions` in
 * `@objectstack/runtime`), and the job service invokes it with
 * `{ jobId, data }` — `IJobService`'s `JobHandler` context — plus the `bundle`
 * the AppPlugin adds. There is deliberately no data engine in that context: a
 * flow function is PURE by default, returning a value a later declarative node
 * persists (#4343 / #4396).
 *
 * A background job is the case that contract does not cover — nothing
 * downstream is going to persist for it — so it does its own I/O over a handle
 * captured at `onEnable`, and DECLARES that in the `functions` map with
 * `effect: 'writes'` (#4396). That declaration grants nothing; it tells the
 * platform this callable's writes are not counted by the caller, so a run
 * reports "cannot say" instead of silently claiming it wrote nothing.
 * `@objectstack/runtime`), and a `script` node's context deliberately carries
 * no data engine: a flow function is PURE, returning a value a later
 * declarative node persists (#4343 / #4396).
 *
 * A JOB is the case that contract does not cover — it has no graph, so no node
 * before it reads and none after it persists. Since #14094 the AppPlugin
 * therefore invokes a job's `functions` entry with a `JobHandlerContext`:
 * `{ jobId, data, bundle }` widened with `ql` (the same engine handle
 * `defineStack({ onEnable })` receives) and `logger`. This handler takes both
 * from that argument, which is the only route that survives the shipped
 * deployment path.
 *
 * ⛔ The shape this file used to have — `onEnable` filling a module-scope
 * `let host` the handler read later — does NOT survive a built artifact, and
 * fails silently rather than loudly. `objectstack build` emits `functions` into
 * a sibling runtime module exporting only `{ functions, meta }`; the artifact
 * JSON carries no `onEnable`, and `mergeRuntimeModule`
 * (`packages/runtime/src/load-artifact-bundle.ts`) merges only `functions`. So
 * on an artifact-served boot the binding was never made, the handle stayed
 * `undefined`, and `showcase_health_sweep` fired on schedule, recomputed
 * nothing, and reported a clean run (#14257). The pin against a return is in
 * `test/inert-wirings.test.ts`, which reaches this handler through its
 * `functions` entry — the one thing an artifact carries — with no `onEnable`
 * anywhere in the test.
 *
 * The entry still DECLARES `effect: 'writes'` in the `functions` map (#4396),
 * and taking `ql` from the argument does not change that: the declaration was
 * never about where the handle came from. A job's writes are counted by no
 * caller — there is no downstream declarative node to count them — so
 * undeclared, a run reports having written nothing instead of "cannot say",
 * which is indistinguishable from the broken sweep #4354 exists to detect.
 *
 * ## What it computes
 *
Expand All@@ -56,6 +75,8 @@
 * so a steady-state sweep performs zero updates.
 */

import type { JobHandlerContext } from '@objectstack/runtime';

/** Statuses whose health is still in play. */
const SWEPT_STATUSES = ['active', 'on_hold'] as const;

Expand All@@ -71,36 +92,6 @@ const SYS = { isSystem: true } as const;

type Health = 'green' | 'yellow' | 'red';

interface JobHostEngine {
 find: (object: string, query: unknown, options?: unknown) => Promise<unknown>;
 update: (object: string, data: Record<string, unknown>, options?: unknown) => Promise<unknown>;
}

interface JobHostContext {
 ql: JobHostEngine;
 logger?: {
 info?: (...a: unknown[]) => void;
 warn?: (...a: unknown[]) => void;
 };
}

/**
 * The engine handle the job runs over, captured from the host context at
 * `onEnable`. Module scope is what makes it reachable from a `functions` entry,
 * which the job service calls with no context of its own — the "closed over a
 * client at module scope" shape `effect: 'writes'` exists to declare.
 */
let host: JobHostContext | undefined;

/**
 * Give `sweepProjectHealth` its data handle. Called from `onEnable` in
 * `objectstack.config.ts`, which is the one place the app is handed a live
 * engine. Idempotent — a re-enable simply rebinds.
 */
export function bindShowcaseJobRuntime(ctx: JobHostContext): void {
 host = ctx;
}

/** Normalize the engine's list shape (array, or `{ records }`). */
function rowsOf(result: unknown): Array<Record<string, unknown>> {
 if (Array.isArray(result)) return result as Array<Record<string, unknown>>;
Expand All@@ -120,7 +111,7 @@ function num(value: unknown): number | undefined {

/**
 * The health verdict for one project — exported so the rule is unit-testable
 * without an engine (see `test/job-health-sweep.test.ts`).
 * without an engine (see `test/inert-wirings.test.ts`).
 */
export function healthFor(input: {
 budget?: unknown;
Expand DownExpand Up@@ -148,20 +139,12 @@ export function healthFor(input: {
 *
 * Registered as `functions.sweepProjectHealth` with `effect: 'writes'` and
 * scheduled by `HealthSweepJob` (`0 1 * * *` UTC).
 *
 * `jobId`, `ql` and `logger` all come off the `JobHandlerContext` the AppPlugin
 * builds per run — there is no binding step, so there is no boot path on which
 * this handler can be reached without them.
 */
export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void> {
 const jobId = ctx?.jobId ?? 'showcase_health_sweep';
 if (!host) {
 // Reached only if the job somehow fires before `onEnable` bound the
 // handle. Functional degradation, not a durability one: nothing claimed to
 // be persisted has been lost, and the next scheduled run recomputes
 // everything from scratch (AGENTS.md "Degradation log levels").
 // eslint-disable-next-line no-console
 console.warn(`[showcase] ${jobId}: no engine handle bound yet — skipping this run`);
 return;
 }
 const { ql, logger } = host;

export async function sweepProjectHealth({ jobId, ql, logger }: JobHandlerContext): Promise<void> {
 const projects = rowsOf(
 await ql.find('showcase_project', {
 where: { status: { $in: [...SWEPT_STATUSES] } },
Expand All@@ -171,7 +154,7 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 }),
 );
 if (projects.length === 0) {
 logger?.info?.('[showcase] project health sweep: no in-play projects', { job: jobId });
 logger.info('[showcase] project health sweep: no in-play projects', { job: jobId });
 return;
 }

Expand DownExpand Up@@ -208,15 +191,15 @@ export async function sweepProjectHealth(ctx?: { jobId?: string }): Promise<void
 await ql.update('showcase_project', { id, health: next }, { context: SYS });
 updated += 1;
 } catch (err) {
 logger?.warn?.('[showcase] project health update failed', {
 logger.warn('[showcase] project health update failed', {
 job: jobId,
 project: id,
 error: err instanceof Error ? err.message : String(err),
 });
 }
 }

 logger?.info?.('[showcase] project health sweep complete', {
 logger.info('[showcase] project health sweep complete', {
 job: jobId,
 scanned: projects.length,
 updated,
Expand Down
Loading
Loading