Operations

Build mechanics, test coverage, operational runbooks, and change impact guidance.

Build and publish pipeline

Feature publish pipeline

Each feature's scripts/publish.js follows this pattern:

1. Build client and server bundles
2. Derive routes from source
3. Derive server function exports
4. Derive shared deps from package manifest
5. Compute SRI map over built assets
6. Sign manifest
7. Upsert and sign releases.json

Artifact layout

artifacts/<featureId>/
  releases.json
  <version>/
    manifest.json
    package.json
    server-functions.js
    <feature assets...>

Release workflow

Commands: canary, promote, rollback

• Always validates existing signed release index before mutation
• Maintains monotonic sequence
• Signs updated index
• Supports provenance fields (gitSha, buildUrl, timestamp)

Recommended operational split:

• Developers publish versions with pnpm run publish -- --feature <id>
• Operators manage channel moves and rollback in /_admin
• pnpm run channel:fallback ... is automation/emergency fallback only

Artifact doctor

pnpm run doctor checks:

• Release signature validity
• Release schema validity
• Manifest hash match
• Manifest signature validity
• Integrity map correctness
• Route conflicts across loaded manifests

Test coverage map

Test file	Main guarantees
manifest-signature.test.js	Signature verification correctness, tamper detection
manifest-tools.test.js	Route extraction, server export extraction, shared dep derivation
release-index.test.js	Release index sequencing, active-version pinning, signature validation
route-conflicts.test.js	Mount overlap and duplicate route conflict detection
feature-sdk.test.js	SDK fallbacks and runtime permission behavior
api-proxy.test.js	Proxy forwarding, plugin enrichment, unconfigured behavior
auth-plugin.test.js	Custom auth plugin hooks for RPC and API enrichment
dfs-auth.test.js	DFS token validation mode and trusted-cluster behavior
hardening.test.js	Rate limit, body limit, timeouts, circuit breaker, CSRF, config validation
remote-cdn-runtime.test.js	Remote index loading, remote assets, remote endpoint RPC proxy
production-readiness.test.js	Full build/publish/serve and critical runtime invariants
browser-integration.test.js	Route accessibility, shell fallback absence, runtime permission denials
browser-auth-flow.test.js	Browser ingress auth flow and token forwarding
e2e-real-auth.test.js	Optional integration against real auth environment

The suite strongly covers integrity, signing, auth, proxy, and runtime primitives. Highest practical risk remains regressions in cross-feature UX flows and feature-specific business logic.

Operational runbooks

Feature shell shows "temporarily unavailable"

Check in order:

1. Browser console: script load error vs runtime error
2. /_health/:featureId: signature and integrity status
3. Manifest entrypoints and integrity map correctness
4. Shared import map emitted (look for react/jsx-runtime mapping in shell HTML)
5. Feature bundle output in artifacts or remote CDN

RPC returns 404, 403, or 503

Status	Cause
404 Feature not found	Manifest not loaded for featureId
403 function_not_declared	fnName missing in manifest.serverFunctions.exports
403 function_not_allowed	Local module exported symbol mismatch with allowlist
503 server_functions_unavailable	No local module loaded and no endpoint configured
503 (proxy)	Endpoint timeout or unavailable

Route unexpectedly inaccessible

• If authRequired: true, inspect auth mode and headers
• If authRequired: false, host should not block based on role, toggle, or tenant policy
• Inspect resolveFeature longest-prefix interactions and route conflicts

Remote CDN not updating

1. FEATURE_REMOTE_INDEX_URL reachable and valid schema
2. Remote releases.json signatures valid
3. Remote manifest signatures and integrity valid
4. FEATURE_REMOTE_POLL_MS non-zero for auto-refresh
5. Check logs for remote.refresh.failed

API proxy 503 with circuit open

• Inspect /_health → apiProxy.circuitBreaker
• Verify upstream health and timeout settings
• After CIRCUIT_BREAKER_RESET_TIMEOUT_MS, one half-open probe is attempted

Change impact map

Add or change host route/middleware

Edit:

• apps/host/src/server.ts
• Related middleware in apps/host/src/middleware/*
• Tests: hardening.test.js, production-readiness.test.js

Change manifest contract

Edit:

• shared/manifest-schema/index.js
• Publish scripts consuming schema
• Tests: manifest-tools.test.js, production-readiness.test.js

Change signing keys or signature semantics

Edit:

• shared/manifest-signature/index.js
• Consumers in host loaders and publish/release scripts
• Tests: manifest-signature.test.js, release-index.test.js

Change release process

Edit:

• shared/manifest-tools/release-index.js
• scripts/release-workflow.js
• Host startup release loading if fields changed
• Tests: release-index.test.js, production-readiness.test.js

Change RPC auth model

Edit:

• apps/host/src/rpc/middleware.ts
• apps/host/src/auth/*
• Tests: dfs-auth.test.js, auth-plugin.test.js, browser-auth-flow.test.js, e2e-real-auth.test.js

Change API proxy or identity model

Edit:

• apps/host/src/api/proxy.ts
• Custom plugin contracts
• Tests: api-proxy.test.js, auth-plugin.test.js, hardening.test.js

Change shell or runtime browser contract

Edit:

• apps/host/src/shell-renderer.ts
• Shared runtime packages: shared/event-bus, shared/host-store, shared/feature-sdk
• Tests: browser-integration.test.js, feature-sdk.test.js, production-readiness.test.js

Change remote CDN discovery

Edit:

• apps/host/src/startup/manifest-loader.ts
• apps/host/src/startup/release-loader.ts
• apps/host/src/startup/integrity-verifier.ts
• Tests: remote-cdn-runtime.test.js

Design constraints

1. No distributed/shared rate-limit state — limiter is in-memory per host instance
2. Fallback cache is in-memory and not persisted across restarts
3. Feature shell render mode is request-per-page-load (no host SPA router)
4. Shared deps mapping is explicit and finite — adding a new shared package requires map updates
5. Visibility evaluator exists in shared tools but host runtime intentionally does not enforce it