Save a session to start your day.
Copy, don't synchronize
Select favorites above to copy to the other database. Existing choices are kept; removals are not propagated.
@@ -269,7 +281,11 @@
Confirm selected favorites
},
});
const data = await response.json();
- if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
+ if (!response.ok) {
+ const error = new Error(`${data.error.code}: ${data.error.message}`);
+ error.code = data.error.code;
+ throw error;
+ }
return data;
}
@@ -279,6 +295,36 @@
Confirm selected favorites
if (id === "message") $(id).className = `notice ${error ? "error" : "success"}`;
}
+ function showFailure(error) {
+ const step = config?.mode === "starter"
+ ? (error.code === "TODO_LIST_SESSIONS" ? 1 : error.code === "TODO_SAVE_FAVORITE" ? 2 : undefined)
+ : undefined;
+ if (step) {
+ $("exercise").hidden = false;
+ $("exercise-title").textContent = step === 1
+ ? "Exercise 1 — Read the catalog" : "Exercise 2 — Save your first favorite";
+ $("exercise-help").textContent = step === 1
+ ? "Your database is reachable. Implement listSessions to make its catalog appear; this is an expected exercise checkpoint, not a system failure."
+ : "The catalog is working. Implement saveFavorite, then try Save favorite again. Your existing favorites have not been reset.";
+ $("exercise-guide").href = `https://github.com/documentdb/ato-2026-workshop/blob/main/docs/lab.md#${step === 1 ? "2-read-the-catalog" : "3-save-favorites-and-prove-persistence"}`;
+ } else {
+ $("exercise").hidden = true;
+ notice("error", error.message);
+ }
+ if (!state) {
+ $("catalog-empty").hidden = false;
+ $("catalog-empty").textContent = step === 1
+ ? "Next: complete Exercise 1 in exercises/starter/repository.js, save, and refresh."
+ : "The catalog could not be loaded. Resolve the error above, then refresh.";
+ $("catalog-source").textContent = step === 1
+ ? "Catalog source and snapshot details will appear after Exercise 1. The attendee guide explains the included schedule."
+ : "Catalog source details are unavailable until this database can be read.";
+ $("status").textContent = step === 1
+ ? "Database reachable. Ready for Exercise 1."
+ : "This request did not complete. Check the error above; no fallback target was used.";
+ }
+ }
+
async function perform(action) {
if (busy) return;
busy = true;
@@ -287,7 +333,7 @@
Confirm selected favorites
try {
await action();
} catch (error) {
- notice("error", error.message);
+ showFailure(error);
} finally {
busy = false;
controls();
@@ -306,7 +352,7 @@
Confirm selected favorites
function renderConfiguration() {
$("target-name").textContent = label(config.target);
- $("mode").textContent = `${config.mode === "starter" ? "TODO starter" : "Complete reference"} / Same application data layer`;
+ $("mode").textContent = `${config.mode === "starter" ? "Exercise implementation (your editable code)" : "Complete reference"} / Same application data layer`;
$("target-select").replaceChildren();
for (const { id: target } of config.targets) {
const option = node("option", label(target));
@@ -362,6 +408,7 @@
Confirm selected favorites
body: JSON.stringify({ target: config.target, sessionId: session.id }),
});
await loadState();
+ $("exercise").hidden = true;
notice("message", saved ? "Removed from the active database only." : "Favorite saved in the active database.");
});
});
@@ -422,6 +469,9 @@
Confirm selected favorites
async function refresh() {
state = undefined;
selected.clear();
+ $("exercise").hidden = true;
+ $("catalog-source").textContent = "Checking this catalog's source and snapshot date...";
+ $("favorites-empty").hidden = false;
$("sessions").replaceChildren();
$("favorites").replaceChildren();
$("copy-results").replaceChildren();
@@ -466,7 +516,7 @@
Confirm selected favorites
link.download = `${state.catalog.kind === "practice" ? "practice-" : ""}conference-favorites.ics`;
link.click();
setTimeout(() => URL.revokeObjectURL(url), 1000);
- notice("message", "Calendar export requested. Save the .ics file if your browser prompts, then import it manually; this is not a live subscription.");
+ notice("message", "Calendar export requested. Save the .ics file if prompted, then follow the Google Calendar / Apple Calendar import steps below the download button. This is a snapshot, not a live subscription.");
}));
$("copy").addEventListener("click", () => {
$("copy-route").textContent = `${label(config.target)} -> ${label(destination())}`;
diff --git a/src/server.js b/src/server.js
index 83610f3..99f9d14 100644
--- a/src/server.js
+++ b/src/server.js
@@ -88,18 +88,18 @@ export async function createApp({ config, connections, repository, logger = cons
}
const target = activeTarget;
if (request.method === "GET" && url.pathname === "/api/health") {
- await connections.db(target).command({ ping: 1 });
+ await (await connections.db(target)).command({ ping: 1 });
json(200, { ready: true, target, mode: config.mode, location: config.location });
return;
}
if (request.method === "GET" && url.pathname === "/api/state") {
- const state = await readPlanner(connections.db(target), repository);
+ const state = await readPlanner(await connections.db(target), repository);
json(200, { target, ...state });
return;
}
if (request.method === "GET" && url.pathname === "/api/calendar") {
assertTarget(url.searchParams.get("target"));
- const state = await readPlanner(connections.db(target), repository);
+ const state = await readPlanner(await connections.db(target), repository);
if (state.orphanedFavorites.length) {
throw new WorkshopError(409, "CATALOG_DRIFT", "Some favorites have no matching session. Resolve the catalog drift before exporting.");
}
@@ -120,14 +120,14 @@ export async function createApp({ config, connections, repository, logger = cons
if (!["local", "site-b", "cloud"].includes(data.nextTarget)) {
throw new WorkshopError(400, "INVALID_TARGET", "Choose one of the configured database targets.");
}
- await connections.db(data.nextTarget).command({ ping: 1 });
+ await (await connections.db(data.nextTarget)).command({ ping: 1 });
assertTarget(data.target);
activeTarget = data.nextTarget;
json(200, details());
return;
}
if (url.pathname === "/api/favorites") {
- const db = connections.db(target);
+ const db = await connections.db(target);
await requireSession(db, data.sessionId);
if (request.method === "POST") {
const result = await repository.saveFavorite(db, data.sessionId);
@@ -142,7 +142,7 @@ export async function createApp({ config, connections, repository, logger = cons
if (data.source !== target || !["local", "site-b", "cloud"].includes(data.destination) || data.source === data.destination) {
throw new WorkshopError(400, "INVALID_TRANSFER", "Copy from the active target to the other configured target.");
}
- const result = await copyFavorites(connections.db(data.source), connections.db(data.destination), data.sessionIds);
+ const result = await copyFavorites(await connections.db(data.source), await connections.db(data.destination), data.sessionIds);
if (!result.complete) {
logger.error(JSON.stringify({ event: "copy_incomplete", statuses: result.results.map((item) => item.status) }));
}
diff --git a/test/connections.test.js b/test/connections.test.js
new file mode 100644
index 0000000..b9f420f
--- /dev/null
+++ b/test/connections.test.js
@@ -0,0 +1,122 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createConnections } from "../src/connections.js";
+import { waitForDatabase } from "../scripts/database.mjs";
+
+const config = { targets: {
+ local: { uri: "mongodb://site-a.invalid", database: "test_a", developmentCertificate: true },
+ "site-b": { uri: "mongodb://site-b.invalid", database: "test_b", developmentCertificate: true },
+ cloud: { uri: "mongodb://managed.invalid", database: "test_cloud", developmentCertificate: false },
+} };
+function mockDriver() {
+ const clients = [];
+ const failure = () => Object.assign(new Error("synthetic failure"), { name: "MongoServerSelectionError" });
+ class Client {
+ constructor(uri, options) {
+ Object.assign(this, { uri, options, connects: 0, closes: 0, topology: null });
+ clients.push(this);
+ }
+ async connect() {
+ this.connects++;
+ if (Client.gate) await Client.gate;
+ // Model the pinned driver's failed-lazy-connect state. Only explicit
+ // connect may repair it; db()/commands never repair a closed topology.
+ this.topology = Client.available ? "connected" : "closed";
+ if (!Client.available) throw failure();
+ return this;
+ }
+ db(name) {
+ return { name, command: async () => {
+ if (this.topology !== "connected" || !Client.available) throw failure();
+ return { ok: 1 };
+ } };
+ }
+ async close() { this.closes++; this.topology = "closed"; }
+ }
+ Client.available = false;
+ return { Client, clients };
+}
+
+test("first failed acquisition retries explicitly on the same cached client, without replaying commands", async () => {
+ const { Client, clients } = mockDriver();
+ const connections = createConnections(config, { Client });
+ await assert.rejects(connections.db("site-b"), { name: "MongoServerSelectionError" });
+ assert.equal(clients[0].topology, "closed");
+ Client.available = true;
+ assert.deepEqual(await (await connections.db("site-b")).command({ ping: 1 }), { ok: 1 });
+ assert.equal(clients.length, 1);
+ assert.equal(clients[0].connects, 2);
+ Client.available = false;
+ await assert.rejects(clients[0].db("test_b").command({ ping: 1 }));
+ assert.equal(clients[0].connects, 2, "a failed operation isn't automatically retried");
+ Client.available = true;
+ await (await connections.db("site-b")).command({ ping: 1 });
+ assert.equal(clients[0].connects, 3);
+ await connections.close();
+});
+
+test("concurrent failed and healthy acquisitions settle, reuse one client, and keep TLS/timeouts", async () => {
+ const { Client, clients } = mockDriver();
+ const connections = createConnections(config, { Client });
+ const failed = await Promise.allSettled(Array.from({ length: 3 }, () => connections.db("site-b")));
+ assert.ok(failed.every(({ status }) => status === "rejected"));
+ Client.available = true;
+ assert.equal((await Promise.all(Array.from({ length: 3 }, () => connections.db("site-b")))).length, 3);
+ assert.equal(clients.length, 1);
+ assert.equal(clients[0].connects, 6);
+ const { options } = clients[0];
+ assert.equal(options.tls, true);
+ assert.equal(options.tlsAllowInvalidCertificates, true);
+ assert.equal(options.tlsAllowInvalidHostnames, false);
+ assert.equal(options.retryWrites, false);
+ assert.equal(options.serverSelectionTimeoutMS, 5000);
+ assert.equal(options.connectTimeoutMS, 5000);
+ assert.equal(options.timeoutMS, 10000);
+ await connections.db("cloud");
+ assert.equal(clients[1].options.tlsAllowInvalidCertificates, false);
+ await assert.rejects(connections.db("unknown"), { code: "TARGET_NOT_CONFIGURED" });
+ await connections.close();
+ assert.ok(clients.every(({ closes }) => closes === 1));
+});
+
+test("close is terminal and idempotent and waits for acquisitions without handing out a closing Db", async () => {
+ const { Client, clients } = mockDriver();
+ Client.available = true;
+ let release;
+ Client.gate = new Promise((resolve) => { release = resolve; });
+ const connections = createConnections(config, { Client });
+ const acquisition = assert.rejects(connections.db("local"), { code: "CONNECTIONS_CLOSED" });
+ const closing = connections.close();
+ assert.equal(connections.close(), closing);
+ assert.equal(clients[0].closes, 0);
+ await assert.rejects(connections.db("site-b"), { code: "CONNECTIONS_CLOSED" });
+ release();
+ await Promise.all([acquisition, closing]);
+ assert.equal(clients.length, 1);
+ assert.equal(clients[0].closes, 1);
+ await assert.rejects(connections.db("local"), { code: "CONNECTIONS_CLOSED" });
+});
+
+test("wait retries acquisition INSIDE its loop, then the original invocation succeeds", async () => {
+ let attempts = 0;
+ let clock = 0;
+ const connections = { async db(target) {
+ assert.equal(target, "site-b");
+ if (++attempts < 3) throw new Error("not ready yet");
+ return { async command(command) { assert.deepEqual(command, { ping: 1 }); } };
+ } };
+ await waitForDatabase(connections, "site-b", { timeoutMS: 6000, now: () => clock, sleep: async (ms) => { clock += ms; } });
+ assert.equal(attempts, 3);
+ assert.equal(clock, 4000);
+});
+
+test("wait deadline is bounded even when every acquisition rejects", async () => {
+ let attempts = 0;
+ let clock = 0;
+ const failure = new Error("unavailable");
+ await assert.rejects(waitForDatabase({ async db() { attempts++; throw failure; } }, "site-b", {
+ timeoutMS: 4500, now: () => clock, sleep: async (ms) => { clock += ms; },
+ }), (error) => error === failure);
+ assert.equal(attempts, 3);
+ assert.equal(clock, 4500);
+});
diff --git a/test/database.integration.js b/test/database.integration.js
index d8700a4..697c754 100644
--- a/test/database.integration.js
+++ b/test/database.integration.js
@@ -1,3 +1,6 @@
+import { inspectDatabase } from "../src/inspection.js";
+import { programCounts } from "../scripts/program-counts.mjs";
+import { programCountsPipeline } from "../examples/complete/program-counts.js";
import test from "node:test";
import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";
@@ -24,21 +27,11 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
const config = readConfig({ ...localEnv, LOCAL_DATABASE_NAME: `verify_source_${runId}` });
const sourceConnections = createConnections(config);
const destinationConnections = createConnections(readConfig({ ...localEnv, SITE_B_DATABASE_NAME: `verify_destination_${runId}` }));
- const source = sourceConnections.db("local");
- const destination = destinationConnections.db("site-b");
- assert.notEqual(config.targets.local.uri.split("@")[1], config.targets["site-b"].uri.split("@")[1], "integration requires two distinct server endpoints");
- // Site A's credentials must not authenticate to Site B (or vice versa).
- for (const [from, to] of [["local", "site-b"], ["site-b", "local"]]) {
- const foreign = createConnections({ targets: { local: {
- ...config.targets[from],
- uri: `${config.targets[from].uri.split("@")[0]}@${config.targets[to].uri.split("@")[1]}`,
- } } });
- try {
- await assert.rejects(foreign.db("local").command({ ping: 1 }), { code: 18 });
- } finally { await foreign.close(); }
- }
+ let source;
+ let destination;
let sourceOwned = false;
let destinationOwned = false;
+ // Register ownership-aware cleanup before the first asynchronous acquisition.
t.after(async () => {
try {
if (sourceOwned) await source.dropDatabase();
@@ -50,6 +43,19 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
}
}
});
+ source = await sourceConnections.db("local");
+ destination = await destinationConnections.db("site-b");
+ assert.notEqual(config.targets.local.uri.split("@")[1], config.targets["site-b"].uri.split("@")[1], "integration requires two distinct server endpoints");
+ // Site A's credentials must not authenticate to Site B (or vice versa).
+ for (const [from, to] of [["local", "site-b"], ["site-b", "local"]]) {
+ const foreign = createConnections({ targets: { local: {
+ ...config.targets[from],
+ uri: `${config.targets[from].uri.split("@")[0]}@${config.targets[to].uri.split("@")[1]}`,
+ } } });
+ try {
+ await assert.rejects(async () => (await foreign.db("local")).command({ ping: 1 }), { code: 18 });
+ } finally { await foreign.close(); }
+ }
await source.createCollection("verification_ownership");
sourceOwned = true;
await destination.createCollection("verification_ownership");
@@ -105,6 +111,10 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
assert.match(drift.results[0].message, /details differ/);
await destination.collection("sessions").updateOne({ _id: ids[0] }, { $set: { room: originalSession.room } });
+ const beforeMigration = await inspectDatabase(source);
+ assert.equal(beforeMigration.session.schemaVersion, 1);
+ assert.equal(Object.hasOwn(beforeMigration.session, "attendanceMode"), false);
+ assert.ok(beforeMigration.favorite.savedAt);
await source.collection("sessions").createIndex({ startsAt: 1, _id: 1 }, { name: "schedule_order" });
const migrate = () => source.collection("sessions").updateMany(
{ catalogVersion: catalog.fingerprint, schemaVersion: 1, attendanceMode: { $exists: false } },
@@ -112,6 +122,12 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
);
assert.equal((await migrate()).modifiedCount, catalog.sessions.length);
assert.equal((await migrate()).modifiedCount, 0);
+ const afterMigration = await inspectDatabase(source);
+ assert.equal(afterMigration.session._id, beforeMigration.session._id);
+ assert.equal(afterMigration.session.schemaVersion, 2);
+ assert.equal(afterMigration.session.attendanceMode, "in-person");
+ assert.equal(afterMigration.favorite.savedAt, beforeMigration.favorite.savedAt);
+ assert.ok(afterMigration.indexes.some(({ name }) => name === "schedule_order"));
await seedCatalog(source, catalog);
assert.equal(await source.collection("sessions").countDocuments({ schemaVersion: 2 }), catalog.sessions.length);
const state = await readPlanner(source, repository);
@@ -120,7 +136,7 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
const app = await createApp({
config: { ...config, mode: "complete" },
- connections: { db: (target) => {
+ connections: { db: async (target) => {
if (target === "local") return source;
if (target === "site-b") return destination;
throw new WorkshopError(409, "TARGET_NOT_CONFIGURED", "No cloud access in this test.");
@@ -167,3 +183,34 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
await app.close();
}
});
+
+test("optional aggregation queries the actual official snapshot on an owned local test database", async (t) => {
+ const connections = createConnections(readConfig({
+ ...process.env, ACTIVE_TARGET: "local", WORKSHOP_SCENARIO: "attendee",
+ LOCAL_DATABASE_NAME: `verify_query_${randomUUID().replaceAll("-", "")}`,
+ }));
+ let db;
+ let owned = false;
+ t.after(async () => {
+ try { if (owned) await db.dropDatabase(); }
+ finally { await connections.close(); }
+ });
+ db = await connections.db("local");
+ await db.createCollection("verification_ownership");
+ owned = true;
+ const catalog = await readCatalog();
+ await seedCatalog(db, catalog);
+ const result = await programCounts(db, programCountsPipeline);
+ // Independent calculation: conference timezone rather than pipeline bounds.
+ const expected = new Map();
+ for (const session of catalog.sessions) {
+ const day = new Intl.DateTimeFormat("en-CA", { timeZone: catalog.timeZone }).format(new Date(session.startsAt));
+ if (day === "2026-10-19") expected.set(session.track, (expected.get(session.track) || 0) + 1);
+ }
+ assert.deepEqual(result.rows, [...expected].map(([_id, entries]) => ({ _id, entries }))
+ .sort((a, b) => b.entries - a.entries || a._id.localeCompare(b._id)));
+ assert.equal(result.rows.length, 17);
+ assert.equal(result.rows.reduce((sum, row) => sum + row.entries, 0), 74);
+ assert.equal(await db.collection("sessions").countDocuments(), 216);
+ assert.equal(await db.collection("favorites").countDocuments(), 0);
+});
diff --git a/test/experience.test.js b/test/experience.test.js
new file mode 100644
index 0000000..3bd63ea
--- /dev/null
+++ b/test/experience.test.js
@@ -0,0 +1,117 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import vm from "node:vm";
+import { readCatalog } from "../src/catalog.js";
+import { inspectDatabase } from "../src/inspection.js";
+import { programCounts, validatePipeline } from "../scripts/program-counts.mjs";
+import { programCountsPipeline } from "../examples/complete/program-counts.js";
+
+async function browser() {
+ const html = await readFile(new URL("../src/public/index.html", import.meta.url), "utf8");
+ const script = [...html.matchAll(/
]*>([\s\S]*?)<\/script>/g)].at(-1)[1];
+ const elements = new Map();
+ const element = () => ({ hidden: true, textContent: "", value: "", children: [],
+ addEventListener() {}, setAttribute() {}, append(...nodes) { this.children.push(...nodes); },
+ replaceChildren(...nodes) { this.children = nodes; },
+ });
+ const context = vm.createContext({ URLSearchParams, Intl, Date, Set, Map, Error, console,
+ document: {
+ getElementById(id) { if (!elements.has(id)) elements.set(id, element()); return elements.get(id); },
+ createElement: element, querySelectorAll: () => [],
+ },
+ });
+ // Exercise the actual page functions without auto-boot/network. Separate HTTP
+ // tests verify the endpoint contracts. This is not a rendered-browser proof.
+ vm.runInContext(script.replace(/ perform\(refresh\);\s*$/, ""), context);
+ vm.runInContext('config = {mode:"starter", target:"local", targets:[{id:"local",label:"Site A"}], scenario:"attendee", location:"codespaces"}', context);
+ return { elements, context, run: (source) => vm.runInContext(source, context) };
+}
+
+test("expected TODOs show a guided checkpoint, not red error or indefinite loading", async () => {
+ const { elements, run } = await browser();
+ run('showFailure({code:"TODO_LIST_SESSIONS",message:"TODO"})');
+ assert.equal(elements.get("exercise").hidden, false);
+ assert.match(elements.get("exercise-title").textContent, /Exercise 1/);
+ assert.match(elements.get("exercise-help").textContent, /listSessions/);
+ assert.match(elements.get("exercise-guide").href, /#2-read-the-catalog$/);
+ assert.doesNotMatch(elements.get("catalog-empty").textContent, /Loading/);
+ assert.doesNotMatch(elements.get("catalog-source").textContent, /Loading/);
+ assert.equal(elements.get("error")?.hidden ?? true, true);
+ run('showFailure({code:"TODO_SAVE_FAVORITE",message:"TODO"})');
+ assert.match(elements.get("exercise-title").textContent, /Exercise 2/);
+ assert.match(elements.get("exercise-help").textContent, /saveFavorite/);
+ assert.match(elements.get("exercise-guide").href, /#3-save-favorites-and-prove-persistence$/);
+ run('renderConfiguration()');
+ assert.match(elements.get("mode").textContent, /Exercise implementation/);
+ assert.doesNotMatch(elements.get("mode").textContent, /TODO|unfinished/);
+});
+
+test("real errors remain errors; completed exercise state is not inferred from mode", async () => {
+ const { elements, run } = await browser();
+ run('showFailure({code:"DATABASE_UNAVAILABLE",message:"Database unavailable"})');
+ assert.equal(elements.get("exercise").hidden, true);
+ assert.equal(elements.get("error").hidden, false);
+ assert.match(elements.get("catalog-empty").textContent, /could not be loaded/);
+ run('config.mode="complete"; showFailure({code:"TODO_LIST_SESSIONS",message:"Unexpected TODO"})');
+ assert.equal(elements.get("exercise").hidden, true);
+ assert.equal(elements.get("error").textContent, "Unexpected TODO");
+});
+
+test("inspect returns actual bounded projected sessions/favorites and index definitions", async () => {
+ const calls = [];
+ const session = { _id: "sample", title: "Published entry", startsAt: "2026-10-19T13:00:00.000Z", schemaVersion: 1 };
+ const favorite = { _id: "sample", savedAt: "2026-10-17T13:00:00.000Z" };
+ const db = { collection(name) { return {
+ async findOne() { return { _id: "catalog", version: "test", fingerprint: "fp" }; },
+ find(filter, options) {
+ calls.push({ name, filter, options });
+ return { sort(order) { calls.at(-1).sort = order; return this; }, limit(count) { calls.at(-1).limit = count; return this; },
+ async toArray() { return [structuredClone(name === "sessions" ? session : favorite)]; } };
+ },
+ listIndexes() { return { async toArray() { return [{ name: "schedule_order", key: { startsAt: 1, _id: 1 }, ignored: "not emitted" }]; } }; },
+ }; } };
+ const before = await inspectDatabase(db);
+ assert.deepEqual(before.session, session);
+ assert.equal(Object.hasOwn(before.session, "attendanceMode"), false);
+ assert.deepEqual(before.favorite, favorite);
+ assert.ok(calls.every(({ limit }) => limit === 1));
+ assert.deepEqual(calls[0].filter, { catalogVersion: "fp" });
+ assert.deepEqual(calls[1].options.projection, { _id: 1, savedAt: 1 });
+ assert.deepEqual(before.indexes, [{ name: "schedule_order", key: { startsAt: 1, _id: 1 } }]);
+ Object.assign(session, { schemaVersion: 2, attendanceMode: "in-person" });
+ const after = await inspectDatabase(db);
+ assert.equal(after.session.schemaVersion, 2);
+ assert.equal(after.session.attendanceMode, "in-person");
+ assert.equal(after.favorite.savedAt, before.favorite.savedAt);
+});
+
+test("optional reference counts match the real fixed snapshot, not attendees or the current day", async () => {
+ const catalog = await readCatalog();
+ const pipeline = programCountsPipeline(catalog.fingerprint);
+ assert.deepEqual(validatePipeline(pipeline), pipeline);
+ assert.equal(pipeline[0].$match.catalogVersion, catalog.fingerprint);
+ const range = pipeline[0].$match.startsAt;
+ const selected = catalog.sessions.filter(({ startsAt }) => startsAt >= range.$gte && startsAt < range.$lt);
+ assert.ok(selected.every(({ startsAt }) => new Intl.DateTimeFormat("en-CA", { timeZone: catalog.timeZone }).format(new Date(startsAt)) === "2026-10-19"));
+ const counts = new Map();
+ for (const row of selected) counts.set(row.track, (counts.get(row.track) || 0) + 1);
+ const expected = [...counts].map(([_id, entries]) => ({ _id, entries })).sort((a, b) => b.entries - a.entries || a._id.localeCompare(b._id));
+ assert.deepEqual(pipeline[1], { $group: { _id: "$track", entries: { $sum: 1 } } });
+ assert.deepEqual(pipeline[2], { $sort: { entries: -1, _id: 1 } });
+ // These values are independently computed from data/catalog.json; changing
+ // the snapshot requires reviewing both the challenge's expected result and test.
+ assert.equal(selected.length, 74);
+ assert.equal(expected.length, 17);
+ assert.deepEqual(expected[0], { _id: "Inclusion & Diversity in Open Source", entries: 10 });
+ let actualPipeline;
+ const db = { collection(name) { return {
+ async findOne() { assert.equal(name, "workshop_meta"); return { _id: "catalog", fingerprint: catalog.fingerprint, version: catalog.version }; },
+ aggregate(stages, options) { actualPipeline = stages; assert.equal(options.maxTimeMS, 5000); return { async toArray() { return expected; } }; },
+ }; } };
+ assert.deepEqual((await programCounts(db, programCountsPipeline)).rows, expected);
+ assert.deepEqual(actualPipeline.at(-1), { $limit: 30 });
+ for (const stage of ["$out", "$merge", "$lookup", "$unionWith"]) {
+ assert.throws(() => validatePipeline([{ [stage]: "forbidden" }]), { code: "READ_ONLY_PIPELINE" });
+ }
+});
diff --git a/test/http.test.js b/test/http.test.js
index 2395839..b99b573 100644
--- a/test/http.test.js
+++ b/test/http.test.js
@@ -8,7 +8,7 @@ test("HTTP target changes are explicit; errors are sanitized and writes require
const calls = [];
const config = { activeTarget: "local", mode: "complete", location: "laptop", targets: { local: {} } };
const connections = {
- db(target) {
+ async db(target) {
calls.push(target);
if (target !== "local") throw new WorkshopError(409, "TARGET_NOT_CONFIGURED", "No cloud target.");
return { command: async () => ({ ok: 1 }) };
@@ -55,7 +55,7 @@ test("unavailable Site B does not switch the active target or fall back after a
const app = await createApp({
config, repository: {}, logger: { error() {} },
connections: {
- db(target) {
+ async db(target) {
calls.push(target);
return { async command() {
if (target === "site-b" && unavailable) {
diff --git a/test/reconnect.probe.mjs b/test/reconnect.probe.mjs
new file mode 100644
index 0000000..98b7f5b
--- /dev/null
+++ b/test/reconnect.probe.mjs
@@ -0,0 +1,43 @@
+// Internal live harness helper, run inside its OWN disposable Compose project.
+// JSON lines keep one connection manager alive across host-controlled outages.
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { createInterface } from "node:readline";
+import { readConfig } from "../src/config.js";
+import { createConnections } from "../src/connections.js";
+
+const config = readConfig();
+assert.equal(config.scenario, "attendee");
+const connections = createConnections(config);
+try {
+ if (process.argv[2] === "snapshot") {
+ const result = {};
+ for (const target of ["local", "site-b"]) {
+ const db = await connections.db(target);
+ const favorites = await db.collection("favorites").find({}).sort({ _id: 1 }).toArray();
+ result[target] = {
+ sessions: await db.collection("sessions").countDocuments(),
+ favorites: favorites.length,
+ favoriteDigest: createHash("sha256").update(JSON.stringify(favorites)).digest("hex"),
+ };
+ }
+ console.log(JSON.stringify(result));
+ } else {
+ console.log(JSON.stringify({ ready: true, pid: process.pid }));
+ for await (const line of createInterface({ input: process.stdin })) {
+ const { expected } = JSON.parse(line);
+ assert.ok(["ready", "unavailable"].includes(expected));
+ const outcomes = await Promise.allSettled(Array.from({ length: 3 }, async () => {
+ const db = await connections.db("site-b");
+ await db.command({ ping: 1 });
+ }));
+ assert.ok(outcomes.every(({ status }) => status === (expected === "ready" ? "fulfilled" : "rejected")));
+ if (expected === "unavailable") assert.ok(outcomes.every(({ reason }) => reason.name?.startsWith("Mongo")));
+ console.log(JSON.stringify({ expected, concurrent: 3, passed: true, pid: process.pid }));
+ }
+ }
+} catch {
+ // Never print a driver's raw message, URI, stack, or supplied input.
+ console.error(JSON.stringify({ error: "RECONNECT_PROBE_FAILED" }));
+ process.exitCode = 1;
+} finally { await connections.close(); }
diff --git a/test/regression-safety.test.js b/test/regression-safety.test.js
new file mode 100644
index 0000000..6445b0f
--- /dev/null
+++ b/test/regression-safety.test.js
@@ -0,0 +1,43 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+
+// These are packaging/scope guards, not substitutes for the live outage test.
+test("live reconnect harness owns a fresh project and never targets an attendee stack", async () => {
+ const source = await readFile(new URL("../scripts/test-reconnect.mjs", import.meta.url), "utf8");
+ assert.match(source, /const project = `ato-reconnect-\$\{randomUUID\(\)/);
+ assert.match(source, /"--project-name", project/);
+ assert.match(source, /"--env-file", join\(directory, "\.env"\)/);
+ assert.match(source, /await setup\(directory, \{\},/);
+ assert.match(source, /delete env\[key\]/);
+ assert.match(source, /127\.0\.0\.1::3000/);
+ assert.match(source, /if \(owned\)/);
+ assert.match(source, /\[\.\.\.base, "down", "--volumes"/);
+ assert.doesNotMatch(source, /system.*prune|volume.*prune|docker.*kill.*\$\(/);
+ assert.match(source, /await appIdentity\(\), identity/);
+ assert.match(source, /waiter\.result/);
+ assert.match(source, /assert\.deepEqual\(await snapshot\(\), before\)/);
+});
+
+test("runtime image includes all live harness fixtures and optional exercises", async () => {
+ const dockerfile = await readFile(new URL("../Dockerfile", import.meta.url), "utf8");
+ for (const directory of ["src", "scripts", "test", "examples", "exercises", "data"]) {
+ assert.ok(dockerfile.includes(`COPY --chown=node:node ${directory} ./${directory}`));
+ }
+ // Root-only docs checks must stay separate: Docker intentionally omits docs.
+ const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+ assert.equal(pkg.scripts.test, "node --test test/*.test.js");
+ assert.equal(pkg.scripts["test:docs"], "node scripts/check-doc-links.mjs");
+});
+
+test("persistent guide and calendar links keep accessible labels and safe new-tab navigation", async () => {
+ const html = await readFile(new URL("../src/public/index.html", import.meta.url), "utf8");
+ assert.match(html, /Attendee guide \(opens new tab\)/);
+ assert.match(html, /Google Calendar \/ Apple Calendar import steps/);
+ assert.match(html, /id="exercise" role="status" aria-labelledby="exercise-title"/);
+ assert.match(html, /id="error" role="alert"/);
+ assert.match(html, /id="status" role="status"/);
+ for (const [, anchor] of html.matchAll(/(]+)>/g)) {
+ if (anchor.includes('target="_blank"')) assert.ok(anchor.includes('rel="noopener noreferrer"'));
+ }
+});
From a3f9c5aeb16f8350b3ece7ca74887987ddc94824 Mon Sep 17 00:00:00 2001
From: Patty Chow <91703531+patty-chow@users.noreply.github.com>
Date: Sat, 17 Oct 2026 06:53:44 -0700
Subject: [PATCH 2/3] Clean up owned reconnect fixtures after handled
interrupts
---
docs/acceptance.md | 39 ++++++-
scripts/test-reconnect.mjs | 121 ++++++++++++++++-----
test/reconnect-interruption.integration.js | 75 +++++++++++++
test/regression-safety.test.js | 18 +++
4 files changed, 218 insertions(+), 35 deletions(-)
create mode 100644 test/reconnect-interruption.integration.js
diff --git a/docs/acceptance.md b/docs/acceptance.md
index ec8894e..498cead 100644
--- a/docs/acceptance.md
+++ b/docs/acceptance.md
@@ -88,11 +88,40 @@ Requires Docker Compose **2.24.4+** for its port override. It creates a fresh ra
random **loopback-only** app port. It ignores ambient workshop credentials and
never adopts an existing project. It stops/starts only its Site B, captures
sanitized pass/fail receipts, and removes **only its own ephemeral project and
-volumes** in `finally`. Normal notebooks and `.env` are untouched. If its own
-cleanup fails, it prints its generated project name/private directory for manual
-review; it does not run a global prune. CI runs it as a separate ephemeral job.
-The application runs directly without file watching in this harness so PID
-identity really establishes no app restart.
+volumes** through a single idempotent cleanup path. **SIGINT / SIGTERM** abort
+in-flight HTTP requests and probe waits, cancel child commands (with a five-second
+force-termination grace), and enter that same cleanup path with a nonzero exit.
+Repeated signals do not cancel cleanup. Its Compose deadline is 120 seconds;
+each resource-inventory check has a 15-second deadline (plus termination grace).
+The private directory is removed only after successful `down` and independent
+empty inventories for the project's **containers, volumes and networks**.
+
+Normal notebooks and `.env` are untouched. If cleanup or verification fails,
+the process exits nonzero and retains its private configuration, printing only
+the generated project name/private directory for manual review; it does not run
+a global prune or claim success. SIGKILL, machine loss, or an unreachable Docker
+daemon cannot guarantee cleanup. CI runs the normal regression as a separate
+ephemeral job. The application runs directly without file watching in this
+harness so checking its PID really establishes no app restart.
+
+Opt-in interruption regression (Docker host, separate from the offline suite):
+
+```sh
+node --test test/reconnect-interruption.integration.js
+```
+
+This creates two fresh owned projects sequentially, sends SIGTERM and SIGINT
+respectively after startup, repeats each signal during cleanup, and independently
+checks nonzero handled exits, absent containers/volumes/networks, and removal of
+only each run's private temporary directory. It does not stop an existing stack.
+
+**Harness-only proof, October 17:** after adding handled-signal cleanup, the
+normal live reconnect regression passed all five recovery/cleanup checks. The
+real interruption test passed both SIGTERM (exit 143) and SIGINT (exit 130),
+including repeated signals during cleanup. Independent filtered inventories
+confirmed zero owned containers, volumes and networks and absent private
+configuration directories for all three runs. These harness results do not
+constitute another Codespace, browser, calendar or Azure acceptance run.
Then reopen/restart the actual attendee Codespace and follow [the lab](lab.md):
verify the friendly first screen, edit TODO 1, save TODO 2, inspect before/after,
diff --git a/scripts/test-reconnect.mjs b/scripts/test-reconnect.mjs
index 126cb97..7bba454 100644
--- a/scripts/test-reconnect.mjs
+++ b/scripts/test-reconnect.mjs
@@ -13,6 +13,19 @@ import { setup } from "./setup.mjs";
const root = fileURLToPath(new URL("../", import.meta.url));
const project = `ato-reconnect-${randomUUID().replaceAll("-", "")}`;
+// Install handlers before the first asynchronous work, including private setup.
+const interrupted = new AbortController();
+let receivedSignal;
+const children = new Set();
+const onSignal = (signal) => {
+ receivedSignal ||= signal;
+ interrupted.abort(new Error("Harness interrupted"));
+ // Cleanup commands are deliberately immune to repeated signals. Their own
+ // deadlines still apply; killing cleanup would recreate the original leak.
+ for (const running of children) if (!running.cleanup) running.cancel();
+};
+process.on("SIGINT", onSignal);
+process.on("SIGTERM", onSignal);
const directory = await mkdtemp(join(tmpdir(), "ato-reconnect-"));
const override = join(directory, "compose.reconnect.yaml");
// Preserve only ordinary runtime environment; explicitly override interpolation
@@ -27,36 +40,50 @@ Object.assign(env, { COMPOSE_PROJECT_NAME: project, WORKSHOP_PORT: "3000",
const base = ["compose", "--project-name", project, "--project-directory", root,
"--env-file", join(directory, ".env"), "-f", join(root, "compose.yaml"),
"-f", join(root, "compose.complete.yaml"), "-f", override];
-const children = new Set();
-function command(args, { timeout = 300000, input = "ignore" } = {}) {
+function command(args, { timeout = 300000, input = "ignore", cleanup = false } = {}) {
+ if (!cleanup) interrupted.signal.throwIfAborted();
const child = spawn("docker", args, { cwd: root, env, stdio: [input, "pipe", "pipe"] });
- children.add(child);
let stdout = "";
- // Capture no stderr: compose/build/driver failures can contain private values.
- child.stdout.on("data", (chunk) => { stdout += chunk; if (stdout.length > 2000000) child.kill(); });
- child.stderr.resume();
let forceTimer;
- const timer = setTimeout(() => {
+ let cancelled = false;
+ const cancel = () => {
+ if (cancelled) return;
+ cancelled = true;
child.kill("SIGTERM");
forceTimer = setTimeout(() => child.kill("SIGKILL"), 5000);
- }, timeout);
- const result = new Promise((resolve) => {
- child.once("error", () => resolve({ ok: false, stdout: "" }));
+ };
+ const running = { child, cleanup, cancel };
+ children.add(running);
+ // Capture no stderr: compose/build/driver failures can contain private values.
+ child.stdout.on("data", (chunk) => { stdout += chunk; if (stdout.length > 2000000) cancel(); });
+ child.stderr.resume();
+ // Closing a cancelled interactive pipe can race a probe's next write.
+ child.stdin?.on("error", () => cancel());
+ const timer = setTimeout(cancel, timeout);
+ running.result = new Promise((resolve) => {
+ // A spawn error is followed by close; wait for close before cleanup so a
+ // cancelled Compose process cannot still create resources after down.
+ child.once("error", () => { cancelled = true; });
child.once("close", (code) => {
- clearTimeout(timer); clearTimeout(forceTimer); children.delete(child);
- resolve({ ok: code === 0, stdout });
+ clearTimeout(timer); clearTimeout(forceTimer); children.delete(running);
+ resolve({ ok: code === 0 && !cancelled, stdout });
});
});
- return { child, result };
+ return running;
}
+const request = (url, options = {}) => fetch(url, {
+ ...options, signal: AbortSignal.any([interrupted.signal, AbortSignal.timeout(20000)]),
+});
async function run(args, options) {
const result = await command([...base, ...args], options).result;
+ interrupted.signal.throwIfAborted();
assert.ok(result.ok, "Scoped Compose command failed (raw output suppressed)");
return result.stdout.trim();
}
const exec = (...args) => run(["exec", "-T", "app", ...args]);
const receipt = (check, details = {}) => console.log(JSON.stringify({ check, passed: true, ...details }));
let owned = false;
+let cleanupPromise;
let probe;
let failure = false;
let phase = "ownership-and-startup";
@@ -71,6 +98,7 @@ try {
await writeFile(override, `services:\n app:\n init: false\n command: ["node", "src/server.js"]\n ports: !override\n - "127.0.0.1::3000"\n`, { mode: 0o600 });
owned = true;
await run(["up", "--build", "-d", "--wait", "--wait-timeout", "240"], { timeout: 600000 });
+ receipt("owned-ephemeral-project-ready", { project, privateDirectory: directory });
for (const target of ["local", "site-b"]) {
await exec("npm", "run", "wait:database", "--", "--target", target);
await exec("npm", "run", "seed", "--", "--target", target);
@@ -79,7 +107,7 @@ try {
assert.match(address, /^127\.0\.0\.1:\d+$/);
const origin = `http://${address}`;
const get = async (path) => {
- const response = await fetch(`${origin}${path}`, { signal: AbortSignal.timeout(20000) });
+ const response = await request(`${origin}${path}`);
assert.equal(response.status, 200);
return response.json();
};
@@ -91,8 +119,8 @@ try {
return result.stdout.trim();
};
const identity = await appIdentity(); // init:false + direct node => actual app PID
- const post = (path, body) => fetch(`${origin}/api/${path}`, {
- method: "POST", signal: AbortSignal.timeout(20000),
+ const post = (path, body) => request(`${origin}/api/${path}`, {
+ method: "POST",
headers: { "Content-Type": "application/json", "X-Workshop-Token": initial.csrfToken },
body: JSON.stringify(body),
});
@@ -108,17 +136,27 @@ try {
const lines = createInterface({ input: probe.child.stdout })[Symbol.asyncIterator]();
const nextLine = async () => {
let timer;
+ let abort;
try {
+ interrupted.signal.throwIfAborted();
const value = await Promise.race([
- lines.next(), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Probe timeout")), 25000); }),
+ lines.next(), new Promise((_, reject) => {
+ abort = () => reject(interrupted.signal.reason);
+ interrupted.signal.addEventListener("abort", abort, { once: true });
+ timer = setTimeout(() => reject(new Error("Probe timeout")), 25000);
+ }),
]);
assert.equal(value.done, false);
return JSON.parse(value.value);
- } finally { clearTimeout(timer); }
+ } finally {
+ clearTimeout(timer);
+ if (abort) interrupted.signal.removeEventListener("abort", abort);
+ }
};
const probeReady = await nextLine();
assert.equal(probeReady.ready, true);
const acquire = async (expected) => {
+ interrupted.signal.throwIfAborted();
probe.child.stdin.write(JSON.stringify({ expected }) + "\n");
const result = await nextLine();
assert.equal(result.pid, probeReady.pid);
@@ -154,7 +192,7 @@ try {
phase = "healthy-client-outage";
// Control: an already healthy client also recovers without target fallback.
await run(["stop", "documentdb-site-b"]);
- assert.equal((await fetch(`${origin}/api/health`, { signal: AbortSignal.timeout(20000) })).status, 503);
+ assert.equal((await request(`${origin}/api/health`)).status, 503);
assert.equal((await get("/api/config")).target, "site-b");
await acquire("unavailable");
await run(["start", "documentdb-site-b"]);
@@ -170,19 +208,42 @@ try {
receipt("concurrent-acquisitions-close-cleanly");
} catch {
failure = true;
- console.error(JSON.stringify({ error: "RECONNECT_REGRESSION_FAILED", phase, message: "A bounded regression check failed; raw command output was suppressed to protect private settings." }));
+ console.error(JSON.stringify({ error: receivedSignal ? "RECONNECT_REGRESSION_INTERRUPTED" : "RECONNECT_REGRESSION_FAILED",
+ signal: receivedSignal, phase, message: "A bounded regression check stopped; raw command output was suppressed to protect private settings." }));
} finally {
- for (const child of children) child.kill("SIGTERM");
- if (owned) {
- const cleanup = await command([...base, "down", "--volumes", "--remove-orphans"], { timeout: 120000 }).result;
- const remaining = await command(["ps", "-aq", "--filter", `label=com.docker.compose.project=${project}`]).result;
- if (!cleanup.ok || !remaining.ok || remaining.stdout.trim()) {
+ await cleanupOwned();
+ process.removeListener("SIGINT", onSignal);
+ process.removeListener("SIGTERM", onSignal);
+}
+if (failure || receivedSignal) process.exitCode = receivedSignal === "SIGINT" ? 130 : receivedSignal === "SIGTERM" ? 143 : 1;
+
+// One path for success, failed assertions, SIGINT and SIGTERM. Keep private
+// configuration for manual recovery if down OR ANY inventory verification fails.
+function cleanupOwned() {
+ return cleanupPromise ||= (async () => {
+ try {
+ console.log(JSON.stringify({ event: "owned-cleanup-started", project }));
+ const pending = [...children];
+ for (const running of pending) running.cancel();
+ await Promise.all(pending.map(({ result }) => result));
+ if (owned) {
+ const cleanup = await command([...base, "down", "--volumes", "--remove-orphans"], { timeout: 120000, cleanup: true }).result;
+ let empty = true;
+ for (const list of [["ps", "-aq"], ["volume", "ls", "-q"], ["network", "ls", "-q"]]) {
+ const remaining = await command([...list, "--filter", `label=com.docker.compose.project=${project}`], { timeout: 15000, cleanup: true }).result;
+ if (!remaining.ok || remaining.stdout.trim()) empty = false;
+ }
+ assert.ok(cleanup.ok && empty, "Owned cleanup could not be verified");
+ }
+ await rm(directory, { recursive: true });
+ if (owned) {
+ receipt("only-owned-ephemeral-project-cleaned", { project, containers: 0, volumes: 0, networks: 0, privateDirectoryRemoved: true });
+ } else {
+ console.log(JSON.stringify({ event: "private-setup-removed", project, privateDirectoryRemoved: true }));
+ }
+ } catch {
failure = true;
console.error(JSON.stringify({ error: "OWN_PROJECT_CLEANUP_FAILED", project, privateDirectory: directory }));
- } else {
- await rm(directory, { recursive: true });
- receipt("only-owned-ephemeral-project-cleaned");
}
- } else { await rm(directory, { recursive: true }); }
+ })();
}
-if (failure) process.exitCode = 1;
diff --git a/test/reconnect-interruption.integration.js b/test/reconnect-interruption.integration.js
new file mode 100644
index 0000000..14a8070
--- /dev/null
+++ b/test/reconnect-interruption.integration.js
@@ -0,0 +1,75 @@
+// Opt-in Docker-host test; NOT part of offline npm test or the app container's
+// database suite. Every subprocess creates its own random project and .env.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawn, execFile } from "node:child_process";
+import { access } from "node:fs/promises";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const execute = promisify(execFile);
+for (const signal of ["SIGTERM", "SIGINT"]) {
+ test(`${signal} routes through owned cleanup; a repeated signal cannot interrupt cleanup`, { timeout: 780000 }, async () => {
+ const child = spawn(process.execPath, ["scripts/test-reconnect.mjs"], {
+ cwd: root, stdio: ["ignore", "pipe", "pipe"],
+ });
+ const events = [];
+ let ownership;
+ let repeated = false;
+ let timedOut = false;
+ let force;
+ const timer = setTimeout(() => {
+ timedOut = true;
+ child.kill("SIGTERM");
+ force = setTimeout(() => child.kill("SIGKILL"), 180000);
+ }, 600000);
+ const closed = new Promise((resolve, reject) => {
+ child.once("error", reject);
+ child.once("close", (code, exitSignal) => resolve({ code, exitSignal }));
+ });
+ // Only parsed harness receipts, never raw child/driver/Compose output.
+ const read = async (stream) => {
+ for await (const line of createInterface({ input: stream })) {
+ let event;
+ try { event = JSON.parse(line); } catch { continue; }
+ events.push(event);
+ if (event.check === "owned-ephemeral-project-ready") {
+ ownership = event;
+ child.kill(signal);
+ }
+ if (event.event === "owned-cleanup-started" && ownership) {
+ repeated = child.kill(signal);
+ }
+ }
+ };
+ try {
+ const readers = Promise.all([read(child.stdout), read(child.stderr)]);
+ const result = await closed;
+ await readers;
+ assert.equal(timedOut, false, "Harness did not reach its owned-project checkpoint within the startup budget");
+ assert.ok(ownership, "No owned-project receipt");
+ assert.match(ownership.project, /^ato-reconnect-[a-f0-9]{32}$/);
+ assert.equal(repeated, true, "Did not send a second signal during cleanup");
+ assert.equal(result.exitSignal, null, "Harness exited via default signal termination instead of cleanup");
+ assert.equal(result.code, signal === "SIGINT" ? 130 : 143);
+ assert.ok(!events.some(({ error }) => error === "OWN_PROJECT_CLEANUP_FAILED"), "Harness reported cleanup failure");
+ const cleaned = events.find(({ check }) => check === "only-owned-ephemeral-project-cleaned");
+ assert.equal(cleaned?.project, ownership.project);
+ assert.equal(cleaned?.privateDirectoryRemoved, true);
+ for (const list of [["ps", "-aq"], ["volume", "ls", "-q"], ["network", "ls", "-q"]]) {
+ // Independently verify every resource family, narrowly by the generated
+ // project label. This test does not adopt/delete any pre-existing stack.
+ const { stdout } = await execute("docker", [...list, "--filter", `label=com.docker.compose.project=${ownership.project}`], { timeout: 15000 });
+ assert.equal(stdout.trim(), "", "Owned resources remain after interruption");
+ }
+ await assert.rejects(access(ownership.privateDirectory), { code: "ENOENT" });
+ console.log(JSON.stringify({ check: "signal-cleanup-independently-verified", signal, project: ownership.project,
+ containers: 0, volumes: 0, networks: 0, privateDirectoryRemoved: true, exitCode: result.code }));
+ } finally {
+ clearTimeout(timer); clearTimeout(force);
+ if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+ }
+ });
+}
diff --git a/test/regression-safety.test.js b/test/regression-safety.test.js
index 6445b0f..3d9bdd3 100644
--- a/test/regression-safety.test.js
+++ b/test/regression-safety.test.js
@@ -19,6 +19,24 @@ test("live reconnect harness owns a fresh project and never targets an attendee
assert.match(source, /assert\.deepEqual\(await snapshot\(\), before\)/);
});
+test("interruptions share cancellable work and verified, signal-resistant owned cleanup", async () => {
+ const source = await readFile(new URL("../scripts/test-reconnect.mjs", import.meta.url), "utf8");
+ assert.match(source, /process\.on\("SIGINT", onSignal\)/);
+ assert.match(source, /process\.on\("SIGTERM", onSignal\)/);
+ assert.match(source, /AbortSignal\.any\(\[interrupted\.signal, AbortSignal\.timeout\(20000\)\]\)/);
+ assert.match(source, /return cleanupPromise \|\|=/);
+ assert.match(source, /if \(!running\.cleanup\) running\.cancel\(\)/);
+ assert.match(source, /child\.kill\("SIGKILL"\), 5000/);
+ assert.match(source, /await Promise\.all\(pending\.map/);
+ assert.match(source, /assert\.ok\(cleanup\.ok && empty/);
+ const cleanup = source.slice(source.indexOf("function cleanupOwned()"));
+ for (const command of ['["ps", "-aq"]', '["volume", "ls", "-q"]', '["network", "ls", "-q"]']) {
+ assert.ok(cleanup.includes(command));
+ }
+ assert.ok(cleanup.indexOf("cleanup.ok && empty") < cleanup.indexOf("await rm(directory"));
+ assert.match(cleanup, /OWN_PROJECT_CLEANUP_FAILED/);
+});
+
test("runtime image includes all live harness fixtures and optional exercises", async () => {
const dockerfile = await readFile(new URL("../Dockerfile", import.meta.url), "utf8");
for (const directory of ["src", "scripts", "test", "examples", "exercises", "data"]) {
From b2a3902dedf63a0bbaa22e8ec4399f5be676e6a9 Mon Sep 17 00:00:00 2001
From: Patty Chow <91703531+patty-chow@users.noreply.github.com>
Date: Sat, 17 Oct 2026 07:05:24 -0700
Subject: [PATCH 3/3] Record successful Codespace attendee and reconnect
acceptance
---
.azure/deployment-plan.md | 5 +++-
README.md | 7 +++---
docs/acceptance.md | 51 ++++++++++++++++++++++++++++++++++++---
docs/organizer.md | 5 ++--
4 files changed, 58 insertions(+), 10 deletions(-)
diff --git a/.azure/deployment-plan.md b/.azure/deployment-plan.md
index 7c0f388..e6d4a5a 100644
--- a/.azure/deployment-plan.md
+++ b/.azure/deployment-plan.md
@@ -71,7 +71,10 @@ Executed on preceding main source (see [dated acceptance](../docs/acceptance.md)
Still requiring environment-specific acceptance (not replaced by those receipts):
-- [ ] This reconnect/onboarding revision's fresh/restarted attendee Codespace and live failure recovery.
+- [x] Reconnect/onboarding revision: restarted attendee Codespace, 47/47 root tests,
+ 2/2 live integration, same-app cold recovery and original-wait-process recovery;
+ interruption cleanup 2/2. See the dated acceptance record for exact source scope.
+- [ ] New cold Codespace creation on this revision (the polish retest reused the existing one).
- [ ] Fresh Organizer profile and representative account/machine capacity checks.
- [ ] Presenter existing-resource rehearsal on the conference laptop/network.
- [ ] Verified backup recording; Apple Calendar UI and repeat-import handling.
diff --git a/README.md b/README.md
index a5dcb3d..84c48af 100644
--- a/README.md
+++ b/README.md
@@ -23,9 +23,10 @@ On the preceding main source, a fresh **two-core attendee Codespace** reached bo
sites in **4m47s**, actual Site A/B checks passed **34/34 plus integration**, Google
Calendar imported **3/3 events**, and a real **local Mac mini → managed Azure**
round trip passed (temporary cloud resource cleaned up). See the
-[acceptance record](docs/acceptance.md) for scope and the first-connection bug found
-along the way. **This reconnect/onboarding revision still needs its own fresh
-acceptance.** Timed human classroom delivery and conference-laptop networking are
+[acceptance record](docs/acceptance.md) for scope. **This reconnect/onboarding
+revision also passed a restarted-Codespace attendee run: 47/47 tests, actual
+browser exercises, and cold first-connection recovery in the same app process.**
+Timed human classroom delivery and conference-laptop networking are
not verified; automated checks are not substitutes.
The web schedule is primary; October 9 Monday/Tuesday PDFs were cross-checked,
diff --git a/docs/acceptance.md b/docs/acceptance.md
index 498cead..a4ae1ce 100644
--- a/docs/acceptance.md
+++ b/docs/acceptance.md
@@ -50,9 +50,51 @@ checks first-use failure, the original waiting CLI process, concurrent clients,
a healthy-client outage control, unchanged favorite digests, and the **same app
PID** across recovery. A test added to source is not an executed live result.
-**Fresh acceptance of this new HEAD is pending.** Do not carry the earlier 4m47s,
-34/34, or Azure/calendar receipts forward as proof of this patch. Record a new
-receipt only after running it.
+## Executed reconnect / attendee-polish acceptance
+
+Recorded October 17, 2026. The same attendee Codespace was restarted and rebuilt
+from `8993fac38709a5d6cdece1f8170ffe9392111d14`, then fast-forwarded to
+`a3f9c5aeb16f8350b3ece7ca74887987ddc94824` for the harness-only cleanup update.
+That update changed no application/UI code; the final record update is docs-only.
+Earlier notebooks, credentials, volumes and solved exercises were preserved with
+private backups and separate fresh notebook database names.
+
+- Final repository-root tests in Codespaces: **47/47 passed**, no skips;
+ **46 local documentation links** checked.
+- Actual two-server database integration: **2/2 passed**, including the optional
+ official-catalog aggregation.
+- Browser flow: blue Exercise 1, edit the first TODO, 216 entries, blue Exercise 2,
+ save overlapping favorites, persistence, initially empty Site B, two records
+ copied, repeat Already present, and a third favorite copied back. Complete-
+ reference switching preserved both solved files and notebook timestamps.
+- **Main-app cold-connection regression:** Site B was stopped before that app
+ process ever acquired it. The browser switch failed with a genuine 503 and
+ stayed on Site A. After starting only Site B, the same browser retry succeeded
+ with the **same server PID, start time, container and request-token hash**.
+ No app restart or code edit was needed to recover.
+- The isolated live harness independently proved recovery of the **original
+ waiting CLI process**, concurrent first acquisitions and a previously healthy
+ client. All scoped cleanup receipts passed.
+- Interruption regressions: **2/2 passed** in Codespaces, including repeated
+ SIGINT/SIGTERM during cleanup and independent empty resource inventories.
+- Actual document inspection showed the same session change from version 1 with
+ no attendanceMode to version 2/in-person. Migration changed **216 then 0**;
+ the favorite timestamp was unchanged. The optional solved database aggregation
+ returned **17 groups / 74 Monday entries**, matching the reference.
+- Actual browser calendar download contained **three events**, validated against
+ the real state. This revision did not repeat the earlier Google Calendar import
+ or managed Azure test; calendar serialization and transfer semantics are unchanged.
+- Resume to first SSH was about **39 seconds**; the explicit revised-code
+ build/start/seed took **27 seconds**, measured separately. Neither is a fresh
+ cold-creation measurement or a promised attendee timing.
+- The exact Codespace was stopped and its **Shutdown** state verified; notebooks
+ and solved work remain retained. No new Azure resources were used in this retest.
+
+Application actions and dialogs used a real browser; code edits used the
+Codespaces CLI after locating the editable files. This is expert-assisted
+acceptance, not a novice or timed classroom study. During premerge testing,
+canonical main guide links still served the previous guide, so the trusted
+branch guide was used; the docs and app are published together.
## How to verify the revision
@@ -130,7 +172,8 @@ Offline UI mocks are not a rendered-browser acceptance test.
## Still unverified delivery gates
-- This patch's fresh/restarted attendee Codespace and live outage acceptance.
+- A brand-new cold Codespace on this revision (the executed polish test restarted
+ the existing Codespace; the earlier 4m47s cold result remains scoped above).
- Fresh Organizer-profile acceptance (not required for attendees).
- Representative attendee accounts, quotas, resource needs, and conference
laptop/Wi-Fi networking; one two-core Codespace measurement is not capacity proof.
diff --git a/docs/organizer.md b/docs/organizer.md
index 1a334e3..e1e52ea 100644
--- a/docs/organizer.md
+++ b/docs/organizer.md
@@ -67,6 +67,7 @@ catalog ownership, bounded two-site startup, and real two-server data flows in C
The preceding source has fresh two-core Codespaces (4m47s; 34/34 plus integration),
Google Calendar (3/3), and actual local Mac mini → managed Azure data-plane proof;
the temporary Azure resource was cleaned up. See the [acceptance record](acceptance.md)
-for limitations and the reconnect defect found. New-HEAD acceptance, human timing,
-and conference-laptop/network proof remain pending. See also the
+for the restarted-Codespace polish retest and verified same-process reconnect fix.
+Human timing, new cold creation on this revision, and conference-laptop/network
+proof remain pending. See also the
[delivery plan](../.azure/deployment-plan.md).