Crystra for DeepSeek Harness

Crystra turns repeatable workflow steps into deterministic execution, reducing unnecessary agent and LLM calls. This repository owns the single public DSH plugin dsh-crystra; its target registration repository is firestige/crystra-dsh.

Execution and Studio are internal modules of this plugin. crystra-execution and crystra-ui-core remain ordinary, independently versioned component dependencies. Domain implementations stay in their component repositories.

Current development state

Install the exact qualified archive selected by the Crystra quickstart using DSH 0.1.1-rc.2. The combination manifest records its component revisions, release URLs, digests and qualification evidence. The distribution starts at 0.1.0. During rename preparation, config/development-inputs.json binds exact component commits and SHA-256 digests. The eight repositories now use their Crystra coordinates. Production candidates reject local file dependencies and require exact published GitHub Release assets.

Use Node 24.12.0, npm 11.6.2 and pnpm 11.23.0. The current checkout consumes qualified component RCs by exact URL and digest:

npm ci --ignore-scripts --no-audit --no-fund
node scripts/verify-candidate-inputs.mjs --cache
npm rebuild better-sqlite3
npm run build
npm test
npm run pack:verify

The build emits one CSP-compatible browser bundle with module identity dsh-crystra. Its Cordis patch registers one plugin and the internal Workspace override. Archives include source and license attribution; internal modules have no separate plugin manifests.

Isolated integration checks

Use DSH 0.1.1-rc.2. Set CRYSTRA_DSH_BINARY to that version's executable when the global DSH differs. Checks use temporary DSH homes and profiles:

npm run qualify:clean-profile
npm run qualify:lifecycle
npm run qualify:provider-routing
npm run qualify:real-harness
CRYSTRA_QUALIFY_TERMINAL=1 npm run qualify:real-harness
CRYSTRA_QUALIFY_INITIALIZATION=1 npm run qualify:real-harness

Real Harness checks cover the Host, Chrome, Delivery, Studio, recorded traces, and downstream unavailability. The terminal fixture mode supplies deterministic owner facts without invoking an LLM. DSH 0.1.1-rc.2 supplies no CSP header; the bundle check separately rejects dynamic code and inline-script injection.

The root plugin loads without pre-existing Execution configuration. /crystra setup prepares configuration and the bound service group; /crystra doctor reports readiness and missing repository role bindings. /crystra services start|stop|status manages the installation's own Compose namespace. These commands are deterministic and do not invoke an LLM. No independent public product installer is shipped. See initialization.

The plugin binds crystra-services-v0.1.0-rc.3. Setup still requires repository role bindings before workflow execution is ready. If a development fixture has no service descriptor, it explicitly reports DEGRADED / CRYSTRA_SERVICE_DESCRIPTOR_UNAVAILABLE.

New RC tags use crystra-dsh-v<version>-rc.N. Stable promotion reuses qualified bytes through GitHub Releases and retains its manual release gate. There is no npm publication stage. Historical release records describe their original artifacts, not this new distribution.

See foundation boundaries, source notice, and security policy.

The release archive bundles only the two digest-verified first-party component packages using npm bundled dependencies. Their registry dependencies remain ordinary root dependencies, resolved for the installation platform. Packaging never copies the development machine's native dependencies. This permits normal DSH installation with pnpm's default URL-subdependency protection enabled.

The Crystra workbench consumes public v8 UI components. Its Trace directory joins the current instance's Execution Delivery inventory to admitted Evidence DELIVERY_ROOT relationships; it preserves exact Task/Workflow identities and execution start times. Missing, expired, ambiguous or unavailable bindings do not select a guessed Trace. Direct exact Trace ID reads remain available.

Conditional authoring stores keep immutable resource candidates separate from the source package. Exact revision reads never silently select the latest candidate. Resource persistence does not imply publication, execution authorization or Agent notification; the explicit design exploration helpers are not shipped in the plugin archive.

For explicitly configured, read-only Task exploration, the root plugin accepts exploration: {taskFile, sourceLockFile, sourceLockDigest, allowFixtures}. Both files must use absolute paths; the SHA-256 pins the source-lock bytes and each source in that lock is rechecked. taskFile uses crystra-task-file@1 with tasks: [{selection: {taskId, goalRevision, planRevision}, projection}]. Each projection follows the conditional crystra-ui-exploration/draft.1 envelope, uses adapter ID crystra-task-file@1, and carries its own expiry and provenance. This option defaults to disabled. Fixture content additionally requires allowFixtures: true. Read-only loopback RPCs expose catalog/read and projection/read; callers cannot choose filesystem paths. The client refreshes every five seconds and clears old content within a ten-second read lease or at snapshot expiry, whichever comes first. The adapter does not create sessions, authorize execution, or supply missing plan graphs/documents/evidence. An owner Task with the same ID takes precedence and never inherits the draft projection.

Optional exploration.workflowFile uses crystra-workflow-file@1 with workflows: [{selection, projection}]. Selection pins definitionId, definitionRevision and workspaceId; the binding uses adapter crystra-workflow-file@1 and the same conditional envelope/source lock as Task. Configure at least one of taskFile or workflowFile. Each definition has one explicitly selected revision; ambiguous duplicate identities are rejected. Workflow projections supply an exact draft directory entry and independent studio, resources, crystallization available/unavailable surfaces. The public v8 components consume validated maps/layouts, read-only resource snapshots and crystallization projections. Missing edits, relations, sessions, Agent events or measured results remain unavailable. No design fixture is bundled. Workflow reads use workflow/catalog/read and workflow/projection/read on the loopback /crystra-exploration channel.

When Workflow exploration is explicitly configured, the read-only crystra_workflow_draft_read tool resolves the live Agent's registered workspace and requires the projection's exact native session binding. It reads only the requested resource revision and returns at most 10,000 characters per call, with a content digest and continuation offset. Source expiry or session binding changes reject the read. Draft references added to native Input neither submit a message nor grant permission to edit, adopt, execute or publish.

Optional Task assets bind the plan document, summary/DAG and execution diagrams to the current plan and full Wave run identity. They use the public inert SVG vocabulary, explicit node-to-Wave selection and native Markdown rendering; malformed identities or active graphics reject the projection. Missing assets remain unavailable. Graph navigation does not start a run.

To enable isolated Workflow resource candidates, additionally configure an absolute exploration.resourceDraftRoot and allowResourceWrites: true. Saving checks the exact base revision/content and writes an immutable candidate under a source-bound namespace, never the source package. Reload and the bound Agent read tool can consume the exact candidate revision. Persisted events stay pending until a separately admitted consumer acknowledges them; saving is not Agent delivery or adoption. Writes default to disabled.

An optional Task inputBinding supplies an exact native workspaceId, absolute packageRoot and sessionId. The dedicated runtime must confirm workspace and session membership before showing Input; archived or revoked bindings hide it. An owner Task always uses its formal Delivery correlation and cannot inherit a draft session. Task and Workflow drafts may use separate native sessions, so navigation preserves each unsent draft without mixing conversation histories.

Task assets.gateContexts optionally supplies read-only evidence context for an exact Gate and declared evidence item. The public context component renders quoted text only; it cannot approve, execute or follow embedded locators. Missing Plan/Trace associations remain explicit unavailable views with a return control.

Workflow resource relations reuse the public UI graph with exact source file, content and revision checks. A saved candidate invalidates the old graph and retained navigation callbacks until a matching projection is supplied. Graph identity remains stable across unchanged owner polls. These relations describe the conditional source snapshot, not observed runtime calls or Agent adoption.

Resource reads expose the persisted pending notification for the exact candidate revision. Reloading preserves it; the UI distinguishes saved draft bytes from Agent delivery. Missing or mismatched delivery evidence never becomes a success.

Optional exploration.allowResourceNotifications: true requires resource write opt-in. Committed resource changes can be sent to the exact bound native Session with non-waking agent.inject, followed by the public Session durability flush. An explicit retry preserves ordered event identity after failure. The UI labels the durable Session receipt separately from model consumption; no model is started and no edit, execution or publication permission is granted by a notice.

Native shutdown can cancel unconsumed inbox notices. The current queue state is read from public inbox splice history; cancellation is shown explicitly and may be retried without duplicating live work. Durable acceptance remains distinct from model consumption, including after restart.