Migration Guide (v1.x)

Breaking changes and migration steps for SDK v1.x releases.

---

v1.x: Observability Simplification

This release simplifies SDK observability by removing the mode toggle and renaming configuration options.

Breaking Changes

1. Removed BootstrapMode type

The mode property and BootstrapMode type have been removed from BootstrapConfig.

Before (deprecated):

import { BootstrapConfig, BootstrapMode } from '@z0-app/sdk';

const config: BootstrapConfig = {
  mode: 'dogfooded',           // REMOVED
  fallback_on_failure: true,
  warn_on_fallback: true
};

After:

import { BootstrapConfig } from '@z0-app/sdk';

const config: BootstrapConfig = {
  fallback_on_failure: true,   // Still works
  warn_on_fallback: true       // Still works
};

2. Renamed systemLedgerStub to observabilityStub

The systemLedgerStub option has been renamed to observabilityStub to better reflect its purpose.

Before (deprecated):

const options: LedgerOptions = {
  systemLedgerStub: env.SYSTEM_LEDGER.get(
    env.SYSTEM_LEDGER.idFromName('system')
  ),
};

After:

const options: LedgerOptions = {
  observabilityStub: env.SYSTEM_LEDGER.get(
    env.SYSTEM_LEDGER.idFromName('system')
  ),
};

Note: The old systemLedgerStub property still works as a fallback but is deprecated. Update to observabilityStub at your convenience.

Automatic Enablement

Observability is now automatically enabled when observabilityStub is provided. No mode toggle required.

Scenario	Behavior
observabilityStub provided	Observability enabled automatically
observabilityStub omitted	No observability (SDK operates normally)

Migration Steps

1. Remove mode from BootstrapConfig:

   const config: BootstrapConfig = {
     mode: 'dogfooded',
      fallback_on_failure: true,
   };

2. Rename systemLedgerStub to observabilityStub:

   const options: LedgerOptions = {
     systemLedgerStub: env.SYSTEM_LEDGER.get(...),
     observabilityStub: env.SYSTEM_LEDGER.get(...),
   };

3. Remove BootstrapMode imports:

   import { BootstrapMode, BootstrapConfig } from '@z0-app/sdk';
   import { BootstrapConfig } from '@z0-app/sdk';

4. Update type annotations (if using BootstrapMode in your types):

   type MyConfig = { mode: BootstrapMode };
   // BootstrapMode no longer exists - use boolean flags instead

New Features

TenantSystemLedger

For multi-tenant deployments (Workers for Platforms), a new TenantSystemLedger class provides per-tenant observability aggregation:

import { TenantSystemLedger, TenantSystemLedgerEnv } from '@z0-app/sdk';

export class MyTenantSystemLedger extends TenantSystemLedger {
  constructor(ctx: DurableObjectState, env: TenantSystemLedgerEnv) {
    super(ctx, env, {
      aggregationIntervalMs: 60_000  // Flush interval (default: 1 minute)
    });
  }
}

See Dogfooding Guide for full documentation.

Test Utilities

New test utilities for mocking Durable Objects in unit tests:

import {
  createMockDOContext,
  createMockDOStub,
  createMockQueue
} from '@z0-app/sdk';

describe('MyLedger', () => {
  it('should work', () => {
    const ctx = createMockDOContext('my-entity');
    const stub = createMockDOStub();
    const queue = createMockQueue();

    // Use in tests...
  });
});

---

Compatibility Matrix

SDK Version	mode property	systemLedgerStub	observabilityStub
< 1.x	Required	Required	N/A
>= 1.x	Removed	Deprecated	Use this

---

Support

If you encounter issues during migration, please open an issue.