Interact with a Stateful Preview and Managed App Data

Enterprise problem: Generated source is not a usable product, and a screenshot cannot show whether a customer can complete a workflow, keep state through a revision, isolate another app’s records, or recover from a bad schema change.

Whole-course context: The incoming artifacts are Day 02’s preview-ready rev-2, sandbox manifest, and immutable agent-run trace, all bound to the approved blueprint; this day advances from generation into preview interaction and managed app data.

Today’s slice: HelixWorks creates an isolated preview runtime with a revision-bound URL, per-app database and object storage, schema and migration controls, snapshots and reset, then layers independent validation around one stateful Workboard workflow.

End-of-day evidence: A customer can inspect the preview receipt, migration and reset records, browser trace, storage-isolation denials, and validation matrix for the exact revision and environment.

Still unsolved: Salesforce, Snowflake, private connectivity, human identity, sharing, production publication, and fleet operations are not granted or implied.

The customer outcome is a reliable, reviewable implementation of 03 generated code validation. This day introduces the mechanism before policy detail and evidence review; it does not repeat the same customer stories in prose, tables, and diagrams.

Control-plane service owns desired state; runtime workers own execution; the policy/release boundary owns privileged effects. Compute: isolated service or sandbox tasks. Storage: PostgreSQL owns durable state, Redis is a bounded cache, object storage keeps artifacts/evidence, and queues are delivery buffers rather than authority.

Implement the topic as an owned state transition with a named controller, durable record, bounded worker action, and observable terminal evidence. Verify a denied or failed path before calling the mechanism complete.

A preview is not proved by a screenshot: the smallest useful claim is that one approved Workboard revision runs in an isolated environment, preserves only its own managed state, and leaves immutable evidence for success, denial, failure, and recovery. The diagrams below reveal that same system without changing its identifiers or authority model.

Optimizing only generation creates an attractive dead end if customers cannot safely publish, change, recover, export, or delete the result. this section therefore keeps the full product lifecycle visible even though today’s implementation and evidence stop at the stateful-preview gate.

Day 03 may produce a release candidate but cannot call it production-ready. Its exit condition is narrower: one source revision is bound immutably to one build, artifact, Software Bill of Materials (SBOM), provenance statement, IaC plan, preview environment, schema, migration lineage, and observed evidence bundle.

The full lifecycle prevents today’s preview evidence from being mistaken for connector, identity, publication, operations, or retirement evidence.

Accept a Day 03 result only as a stateful-preview result; keep every later lifecycle gate visibly open and unclaimed.

Adding runtime internals before the reader can state the customer claim obscures what must be proved. At minimum, the creator acts through a governed preview control, Workboard changes tenant-scoped managed state, and an independent verifier compares the visible result with authoritative side effects.

This model covers every Day 03 use case without inventing another system: D03-UC-01 admits the revision, D03-UC-02 and D03-UC-03 exercise rows and objects, D03-UC-04 changes schema without losing accepted state, and D03-UC-05 restores or resets only the named environment.

One complete loop connects admission, customer interaction, authoritative state, and independent observation before provider detail appears.

If a proposed check cannot identify the admitted revision, the customer-visible outcome, and the authoritative state observation, it is not an end-to-end preview proof.

A sandbox product can isolate compute yet still leave application authentication, tenant authorization, data ownership, and evidence correlation to the platform using it, so provider features cannot be treated as compliance conclusions. Expand the three boxes into four independently governed boundaries: provider/control plane, hosted runtime, generated Workboard application, and the connector/source boundary that remains closed today. The provider-neutral control plane owns policy and evidence; a Daytona or Cloudflare adapter supplies only the demonstrated runtime observations it can produce.

When one service can rewrite source, change policy, build artifacts, provision data, and declare its own success, compromise or error becomes self-approving and evidence loses independence. Single Responsibility Principle (SRP) boundaries separate each decision, while Don’t Repeat Yourself (DRY) means every service consumes one canonical revision manifest rather than copying app, tenant, region, toolchain, and policy values into provider-specific scripts.

A digest on the final archive cannot show which source, dependencies, tests, and policies produced it, so the complete system closes every Day 03 path in an append-only, content-addressed chain from source through customer-visible evidence. Any changed byte creates a new node rather than updating a prior record.

Hermetic means the build reads only declared inputs in a clean worker, with a pinned operating-system/build image, toolchain, package manager, lockfile, locale, time zone, and command list. Network is disabled after approved dependency material is staged; caches are either empty or addressed by verified digests. Reproducibility is tested by building the same manifest twice in fresh workers, normalizing declared nondeterministic metadata such as archive timestamps, and comparing artifact and SBOM digests. A mismatch blocks promotion and preserves both outputs plus a diff; it is never averaged away or relabelled flaky.

A static render can look correct while buttons, writes, refreshes, and revision changes fail, so customers need a real but non-production place to use the generated app. A preview is a control-plane registration that routes an expiring URL to one app environment and one source revision running in an isolated preview runtime.

The preview gateway validates the preview identifier, expiry, audience policy, and route before forwarding traffic. Possessing a preview URL does not grant project membership, source editing, generated-app membership, another preview, or production access. The companion authorization course configures human application identity; today’s lab uses synthetic preview principals issued only for this isolated environment.

The runtime executes a built artifact for rev-2 with explicit configuration, resource limits, network policy, app-scoped storage bindings, and a short-lived workload identity. It receives secret handles rather than secret values in source or browser code. The preview record names its application, revision, schema version, storage namespace, created time, expiry, owner, and reset policy.

Updating source does not mutate a running preview invisibly. HelixWorks builds a candidate, runs admission checks, records the new artifact digest, then atomically changes the preview binding from rev-2 to rev-3. Failed builds leave the previous preview usable and visible as the active revision.

A shared database credential or object prefix can let generated code from one app read another app’s state, turning a preview defect into cross-project exposure. Managed data is therefore provisioned per app and environment with explicit ownership, namespace, policy, quotas, and lifecycle.

The database stores structured domain records and enforces schema constraints and transactions. Object storage stores blobs such as attachments under opaque keys and metadata; generated apps never construct global bucket paths or receive a bucket-wide credential. A broker issues the preview runtime narrowly scoped access to app:workboard/environment:preview, and server-side application policy still decides which domain actor may access a particular record or object.

Generated code can expect columns that do not exist or apply a destructive migration that makes an earlier artifact unusable, so data evolution must be ordered and recoverable. A schema defines permitted data shape; a migration is a versioned transition between schemas; a snapshot is a point-in-time recovery copy; reset deliberately returns a preview environment to a declared baseline.

The migration controller, not generated application startup, holds schema-change authority. It checks that the migration ID follows the recorded parent, obtains an environment-scoped lock, captures a pre-change snapshot, applies the migration once using an idempotency key, verifies constraints and representative data, then records the schema digest. Application traffic switches only after compatibility checks pass.

Prefer backward-compatible expansion before contraction: add nullable or defaulted fields, deploy code that understands both versions, backfill with checkpoints, then remove old fields in a later governed change. An artifact rollback and a database rollback are different operations. Restoring old code may not understand a new schema, while reversing a migration may lose accepted writes; the preview controller must state which artifact-schema pairs are compatible.

A snapshot is not a backup claim until restore is tested. Restore into a replacement namespace, verify record counts, checksums, constraints, object references, and isolation, then switch the preview binding. Reset is intentionally destructive to preview data and requires a confirmation showing the exact app, environment, target seed, snapshot policy, and consequence. It never touches production or source-system data.

An automatic rebuild can silently pair new code with old assumptions or erase customer-created fixtures, making failures impossible to reproduce. The preview loop keeps source revision, artifact digest, schema version, and data namespace visible as separate bindings.

When the customer requests a change, HelixWorks creates rev-3-draft in the project and runs the bounded Day 02 agent workflow. A successful build creates a candidate artifact; static and migration-plan gates run before any data change. If the change needs m002, the controller snapshots, migrates, verifies, then changes the preview binding. The customer sees a short maintenance state rather than requests split across incompatible versions.

Preserving state is a policy choice, not a default promise. A compatible revision reuses the current preview data namespace. A reset-required revision explains why and offers an export or snapshot according to policy. A fork creates a new namespace from an approved snapshot so experiments cannot mutate the original preview.

Each visible preview page should expose a non-secret build label such as preview-42 / rev-3 / schema-v2. A customer report can then name the exact state. Cache keys include preview, artifact, and schema compatibility identifiers so an old response cannot masquerade as the new revision.

Separate demonstrations of rendering, persistence, migration, and reset can all pass while their composition fails, so the primary lab crosses those seams in one customer workflow. It uses only synthetic Workboard principals and data; identity federation and production access remain out of scope.

1. Create preview preview-42 from rev-2, verify its receipt binds Workboard, the preview environment, artifact digest, schema v1, database namespace, object namespace, expiry, and runtime policy.
2. Open the URL as synthetic Alpha editor, create “Prepare launch notes,” attach brief.txt, mark the todo complete, refresh the browser, and verify record plus attachment persist.
3. Open a synthetic Beta-scoped request for the Alpha todo and object key. Require a neutral denial, unchanged row and object state, and no existence leak.
4. Request the blueprint-compatible change “add optional completion note.” Generate rev-3, inspect migration m002, capture a snapshot, migrate, and atomically update the preview.
5. Verify the original completed todo and attachment remain visible; add a completion note; confirm schema-v2 and rev-3 are displayed.
6. Inject a failing migration verification in a disposable fork. Require the original preview binding and data to remain intact and record the replacement-store restore result.
7. Reset preview-42 to the approved seed after explicit confirmation. Verify user-created rows and objects are removed only from that preview and the schema remains at the declared baseline version.

A successful browser path can coexist with unsafe queries, inaccessible controls, visual breakage, or unacceptable latency, so one end-to-end test cannot carry the whole assurance claim. A validation matrix maps each blueprint criterion to independent gates whose different strengths cover static source, domain logic, real boundaries, user interaction, and quality budgets.

Run cheap deterministic gates first. Pin the package manager, lockfile, runtime image, commands, and clean-workspace requirement. Unit tests exercise state transitions, roles, idempotency, and property-generated sequences with recorded seeds and smallest failing inputs. Integration tests use the production-equivalent database engine, real migrations, object broker, transactions, and Alpha/Beta same-local-ID fixtures.

Browser tests select controls by accessible role and name, wait for named visible or network state rather than sleeps, and capture trace, console, failed requests, screenshot states, browser version, and accessibility tree. Hiding a button is not authorization, so direct API and object calls prove denial with no mutation. Visual baselines cover empty, populated, validation-error, narrow, and zoomed states under pinned rendering conditions.

Target Web Content Accessibility Guidelines (WCAG) 2.2 Level AA where applicable, combining automated rules with keyboard, focus, reflow, status-announcement, and assistive-technology checks. Performance evidence names dataset, request mix, concurrency, geography, database tier, cache state, warm-up, browser profile, percentiles, errors, throughput, and asset budgets. A skipped, stale, flaky, or wrong-revision gate is not-run or failed evidence, never an inferred pass.

Workboard alone may hide storage assumptions that fail for analytical reads or untrusted public writes, so bounded reference probes challenge the shared platform mechanisms. They are not additional full labs and do not claim every archetype is implemented.

Preview evidence can become dangerous if a result for one revision, actor, or namespace is reused for another, so every material observation carries enough context to reject mismatches. Store immutable raw artifacts separately from the append-only index.

Validation and data controls drift into folklore when teams cite generic best practices, so reviewable criteria should point to versioned primary standards. These official sources anchor security, accessibility, and secure-development claims while leaving application-specific threat analysis explicit.

• OWASP Application Security Verification Standard — versioned application-security requirements for server, API, session, file, and data controls.
• W3C Web Content Accessibility Guidelines 2.2 — normative success criteria for the declared accessibility target.
• NIST SP 800-218, Secure Software Development Framework 1.1 — lifecycle practices for verification, vulnerability response, and preserved evidence.
• NIST SP 800-53 Rev. 5 — control catalog covering access, audit, configuration, contingency, and system integrity concerns relevant to managed preview environments.

Managed preview architecture contains many moving parts, and customers need the few governing distinctions kept visible. Carry these rules forward before any enterprise source is connected.

• A preview is a revision-bound non-production endpoint, while a runtime is the isolated compute that serves it.
• Per-app, per-environment database and object grants prevent ambient cross-project data access.
• Schema migration, artifact rollout, snapshot restore, and destructive reset are separate controlled operations.
• One stateful Workboard lab proves interaction, persistence, revision, isolation, migration, and reset composition.
• Layered gates make bounded claims; missing, stale, skipped, or flaky evidence cannot be called a pass.

A preview can appear functional while its revision, data, or recovery boundary is wrong, so completion requires both customer interaction and independent state evidence. Every checked item should identify the exact preview environment.

• [ ] The preview receipt binds app, revision, artifact, schema, stores, policy, owner, and expiry.
• [ ] Preview-link, project, runtime, app, connector, and production authority remain distinct.
• [ ] Database and object access are scoped per app and environment with no ambient credential.
• [ ] The Workboard flow persists across refresh and a compatible revision.
• [ ] Alpha/Beta and cross-app database and object denials prove no read, write, or existence leak.
• [ ] Migration is locked, apply-once, snapshotted, verified, and compatibility-checked.
• [ ] Failed candidate rollout leaves the active preview and original data intact.
• [ ] Reset names its destructive scope and proves other environments are unchanged.
• [ ] Validation spans static, unit/property, integration, browser, accessibility, visual, performance, and abuse evidence.
• [ ] Evidence rows contain actor/resource/scope, precondition, expected, observed, immutable IDs, timestamp, and environment.

Before adding a preview database, prove the smallest tenant-scoped storage rule in in-memory-blueprints.ts. Northstar's supplier-onboarding records must never be addressable through another organization's key.

public find(
  tenantId: TenantId,
  id: BlueprintId,
  version: number,
): Promise<ApprovedBlueprint | null> {
  return Promise.resolve(this.#records.get(`${tenantId}:${id}:${version}`) ?? null);
}

public async commit(blueprint: ApprovedBlueprint, event: BlueprintApprovedV1): Promise<void> {
  const key = `${blueprint.tenantId}:${blueprint.blueprintId}:${blueprint.version}`;
  if (this.#records.has(key)) {
    throw new BlueprintConflictError('Blueprint version is immutable');
  }
  await this.outbox.append({
    id: event.eventId,
    tenantId: event.tenantId,
    event,
    createdAt: blueprint.approvedAt,
    publishedAt: null,
    attempts: 0,
  });
  this.#records.set(key, blueprint);
}

The code declares two invariants: every lookup includes the tenant, and an approved version is insert-only. The repository adapter interprets those rules and changes its record map plus outbox. Locally that is RAM; a durable adapter must enforce equivalent composite keys and transactionality on database CPU, memory, disk, and network. A successful same-tenant read, a null cross-tenant read, and an immutable-version conflict are evidence.

SRP keeps storage mechanics out of the blueprint domain. DRY reuses tenant and blueprint ID types. IoC/DI lets the same application service receive an in-memory test adapter or PostgreSQL adapter. MVC prevents UI state from becoming authority. PubSub gets its event from the same unit of work; IaC supplies isolated environment databases and encryption. The rule is portable even when the mechanism changes.

pnpm vitest run services/control-plane/src/control-plane.test.ts
pnpm smoke:product

Attempt a read with a different tenant, commit the same version twice, and simulate an outbox failure. Passing evidence means no record crosses the tenant key, duplicates conflict, and a failed event append leaves no approved record. This is a foundational storage proof, not a claim that the current monorepo already supplies the preview runtime, migration engine, object scanner, or restore workflow described earlier in the lesson.