Product Contract

The single canonical definition of what BlackLake is, what its parts are called, and what each one is responsible for. If anything in marketing copy, package metadata, product UI, or other docs conflicts with this page, this page wins and the conflicting copy is the bug.

The names#

bl is a short alias for the blacklake binary. blx is the shell wrapper (blx git push, blx terraform apply). Both ship in the same package.

The legacy scoped packages — @blacklake-systems/surface-cli, @blacklake-systems/surface-sdk, @blacklake-systems/depth-cli, @blacklake-systems/depth-sdk, and the standalone blx package — are not the install path. They remain published as deprecated thin re-exports through the migration window. New code should import from blacklake and run blacklake (or bl, blx) on the command line. See Migration from old packages.

What each layer owns#

Surface owns the control loop. Every consequential AI action — a tool call, a CLI command, a CI deploy step, a workflow step, an audit-stream event — can be routed through Surface for a policy decision (allow, deny, approval_required). Surface persists the decision as an immutable evaluation, attaches cost, can hold the call for human approval, and emits a signed receipt. Surface also stores agents, tools, bindings, policies, budgets, approvals, action results, cost records, audit ingest, and MCP upstream registrations.

Depth owns durable execution. Workflows are async TypeScript functions composed of step() calls. Depth persists every step's input and output to SQLite, replays completed steps on restart, supports timers, signals, approvals, and tool/LLM calls. Depth runs locally by default; the developer's machine is the worker. Surface is optional — Depth can run without it.

blx owns the shell capture path. blx <command> classifies the command, calls Surface's govern(), waits for an approval if the policy demands one, then runs the underlying child process and posts the action result back. It is a control wrapper around an existing binary, not a replacement for it.

Composition rules#

These are non-negotiable product invariants. Code or copy that violates them is the bug.

1. One package, explicit layers. blacklake is the install. Surface and Depth are the layers inside it. Engineers never npm install Surface and Depth separately.
2. No forced adoption. Surface must be useful without Depth. Depth must be useful without Surface. The combination must be better than either alone.
3. Customer-owned execution comes first. The default cloud story is: BlackLake controls and analyses the work; the customer's agents, CLIs, automations, SDKs, and workflows execute in their environment. Hosted Depth execution is a future option, not the base assumption.
4. Hosted Depth is quota-gated. If and when BlackLake runs workflows in our cloud, we cap concurrency, wall-clock time, step count, retry count, state size, and provider spend from day one.
5. Receipts bind the whole chain. A governed step's receipt traces to actor, workflow, run, step, tool/model, policy snapshot, approval chain, cost, and outcome. Cross-layer lineage is a first-class field, not a post-hoc join.

The four-question test#

Read this page once and you should be able to answer all four.

Q1 — Can I use Surface without Depth?#

Yes. Surface is the control plane. Call govern() from any TypeScript code, any CI workflow, any shell command (via blx), or any agent that speaks MCP. Depth never has to be involved.

import { govern } from 'blacklake';

const decision = await govern({
  apiKey: process.env.BLACKLAKE_API_KEY,
  agent: 'expense-bot',
  tool: 'stripe.refund',
  action: { amount: 4200 },
});

Q2 — Can I use Depth without Surface?#

Yes. Depth runs durable workflows locally with SQLite as the checkpoint store. With no BLACKLAKE_SURFACE_URL set, Depth executes steps, persists their output, supports replay and signals, and never contacts a control plane.

import { workflow, step } from 'blacklake';

export default workflow('research', async (ctx) => {
  const data = await step(ctx, 'gather', async () => {
    return await ctx.llm('anthropic:claude-sonnet-4-6', {
      prompt: 'Find recent papers on AI governance',
    });
  });
  // ...
});

This is "Depth-only" mode. Steps can still call your own LLM credentials and your own local tools. Approvals are not available without Surface — those require a control plane to record the pending decision and a human to act on it.

Q3 — Can I connect Depth to cloud Surface?#

Yes. Set BLACKLAKE_SURFACE_URL=https://api.blacklake.systems and BLACKLAKE_API_KEY=bl_… in the environment Depth runs in. Depth will:

• Call govern() before each consequential step.
• Record evaluations, approvals, action results, and cost records on the cloud control plane.
• Pause durable runs that hit approval_required and resume the exact paused step after the approval resolves.

The Depth worker still runs on the developer's or customer's machine. Cloud Surface is the analytics and control plane; the workflow code executes locally.

Q4 — Does BlackLake currently run my workflows in its cloud?#

No. Cloud BlackLake hosts Surface — the control plane. It does not yet host Depth workers. Customers run Depth locally or on their own infrastructure today. Hosted Depth is a planned execution option gated on quota, billing, and abuse controls; it is not the base assumption and not silently shipped.

What changes if any of this changes#

Any of the following events trigger a contract update — this page first, then everything that points at it:

• A package other than blacklake becomes a primary install path.
• Surface or Depth grows a hard dependency on the other.
• BlackLake begins executing customer workflows in its own cloud.
• The composition rules above stop holding.

The pattern is: change this document, then sweep stale strings out of repo docs, package metadata, CLI help, console copy, error messages, and site docs.