Cordis Fabric Workspace

English | 中文

The Fabric/Mixin extension layer for DSH as a self-contained workspace of three packages plus an installable profile bundle carrier. The workspace mirrors the upstream fabric split: a pure-Cordis pair (cordis-fabric, cordis-fabric-api) and the DSH integration package (cordis-fabric-dsh) that supplies the Host and browser facades, the package invariant, and the profile bootstrap.

Packages

Package	Kind	Contents
cordis-fabric	pure Cordis	Trusted load-time transformation service (FabricService, bootstrapFabric), Orchestrion transform, node-loader hooks, bridge, browser transform, testkit. No DSH imports.
cordis-fabric-api	pure Cordis	Cooperative compat facade over the fabric registry: FabricCompatService + buildCompatInstrumentations. Peers only Cordis and cordis-fabric.
cordis-fabric-dsh	DSH-facing	Mod-facing facades (ctx.fabricAgent, ctx.fabricTools, ctx.fabricPrompt, ctx.fabricCommands), browser facade (ctx.fabricClient), the package invariant, and the profile bootstrap (installFabricBootstrap).

Only these three packages exist as code in this repository. Anything outside them — for example the official @deepseek-ai/dsh-tool-cordis toolset or a corrected upstream dependency — is never added as a fourth package; it is applied as a pnpm dependency patch stored in patches/ (see patches/README.md).

Repository shape

package.json              # workspace root and dsh.bundle bundle carrier
pnpm-workspace.yaml       # packages/* workspace
cordis.patch.yml          # explicit Fabric profile rows (opt-in, disabled)
AGENTS.md                 # repository-local contributor rules
docs/                     # detailed Fabric, API, and contract references
patches/README.md         # pnpm dependency-patch contract
scripts/                  # self-contained prepare and boundary verification
packages/
  cordis-fabric/          # pure transformation service + browser client entry
  cordis-fabric-api/      # pure compat facade (peer-only library)
  cordis-fabric-dsh/      # DSH facades, invariant, profile bootstrap
lib/                      # build outputs (ignored; each package prepares its own on install)

Repository boundary

This repository is fully self-contained: every source file, compiler setting, test fixture, contributor instruction, and build helper lives below this repository root, and every development input resolves from this repository's own manifests and lockfile. The DSH host packages (@deepseek-ai/dsh-agent, @deepseek-ai/dsh-invariants, and the other @deepseek-ai/dsh-* services the facades delegate to) are installable from the npm registry; the facades import their real types directly (declared as peer + dev dependencies), and a composed DSH profile supplies the real services at runtime.

Run pnpm run verify:self-contained to enforce the boundary: it rejects local-path dependency specs, compiler or code paths that leave the repository, external or broken Markdown links, absolute workstation paths, and the removal of any repository-layout contract.

Bundle behavior

The bundle carrier adds both profile rows as disabled opt-ins:

- id: cordis-fabric
  name: 'cordis-fabric'
  disabled: true

- id: cordis-fabric-dsh
  name: 'cordis-fabric-dsh'
  disabled: true

Fabric patch handlers are trusted code registered through ctx.fabric.register(). Patch descriptors are configuration metadata, but executable handlers are never deserialized from YAML or model input. The service supports Node ESM/CommonJS load-time transformation, browser build-time transformation, priority composition, HMR-safe disposal, static target validation, generator delegation, and watched browser transforms.

The bundle patch only composes these package rows. The launcher/bootstrap wiring the trio needs to RUN is supplied at launch by the plug-and-play fabric-dsh command — the host source stays completely untouched (the host patch is now empty; see patches/README.md). Running plain dsh walks official code only; fabric-dsh injects the loader hooks.

Installation

The bundle installs through DSH's official bundle-plugin channel; the trio resolves from this same GitHub repository through git subdirectory specs, so nothing is published:

dsh plugin --profile web add github:dsh-external/fabric

Restart the web app afterwards. The profile rows are disabled opt-ins; enable cordis-fabric / cordis-fabric-dsh in the profile composition to activate the Fabric layer.

The repository carries no build artifacts: the trio's prepare scripts build lib/ during a Git install (pnpm installs the package's devDependencies and runs prepare on the consumer machine). Installations track main.

For the Fabric layer to actually engage, the load-time transformation hooks must exist before any target module import. The fabric-dsh launcher does exactly that with zero host changes. It ships inside the installed bundle, so once the profile has the bundle, no bundle checkout is needed — run the profile's own bin:

# against a plain official deepseek-harness checkout
$DSH_HOME/profiles/web/node_modules/.bin/fabric-dsh \
  --harness <deepseek-harness-checkout> web --port 8000

(home and profile derive from the install path; the checkout form node <bundle-repo>/scripts/fabric-dsh.mjs --harness <checkout> --profile web ... stays available for development.)

First-time setup from this bundle repo: pnpm run install:host -- <deepseek-harness-checkout> [--dsh-home <dir>] — harness deps + build, profile seed (pnpm settings the git-resolved trio needs), bundle install through the official plugin channel (dsh plugin --profile web add github:dsh-external/fabric, which joins cordis-fabric-bundle to dsh.profile.bundles), and the cordis-fabric-dsh row enable. The host patch is empty, so nothing is patched or branched.

fabric-dsh composes the profile's patch layers, writes the composed descriptors to $DSH_FABRIC_CONFIG, injects packages/cordis-fabric/preload.mjs through --import (which registers the loader hooks before the CLI entry loads, resolving the trio from the profile so hooks and plugins share one module instance — healing the profile's module fallback first, since the preload runs before the CLI's own boot heals it), pins the tsx tsconfig, and appends the profile's pnpm settings (blockExoticSubdeps: false, dangerouslyAllowAllBuilds: true) when missing. A row that declares config.fabric.patches is Fabric-required: it ships disabled, and fabric-dsh enables such rows through a generated overlay — a plain dsh boot skips them entirely (the app runs, the dependent plugins stay unloaded), while fabric-dsh loads them with the hooks installed; the Host plugin then verifies required bindings one tick after boot, and a Fabric-required row explicitly enabled on plain dsh fails the launch loud.

npm-installed official dsh — cannot run fabric-dsh (its CLI ships prebuilt and there is no source entry to preload); it works once the official repository merges the wiring (the fork at 65bcaf9902 contains it).

Two prerequisites:

• pnpm resolves GitHub dependencies over SSH, so the installing machine needs GitHub SSH access for dsh-external/fabric.
• The launch must go through fabric-dsh (plain dsh never activates the Fabric hooks); see above.

Development

pnpm install
pnpm run verify:self-contained
pnpm run typecheck
pnpm test
pnpm run build

lib/ is a build output, never committed: it is recreated by the trio's prepare scripts (the root build script runs them locally). In this workspace, the root manifest's git subdirectory specs for the trio are redirected to the local packages through pnpm-workspace.yaml overrides, so pnpm install never re-clones the repository.

Model Experience

The low-level transformer contributes no model-visible content. The cooperative facades delegate prompt, tools, commands, agent events, and browser command/slot registrations to their authoritative DSH services; those owners retain logging, permissions, approval, cancellation, and rendering semantics.

Known Limitations and Deferred Work

• Node load-time transformation requires precompiled JavaScript; browser transforms strip TypeScript before applying handlers.
• The browser faces are split across the two dual-face packages (cordis-fabric/client for the bridge and service, cordis-fabric-dsh/client for the Mod-facing facade); consumers that need the complete typed SlotMap should use the authoritative DSH slot service instead of widening the facade.
• On an npm-installed official dsh, fabric-dsh cannot run (the CLI ships prebuilt and there is no source entry to preload); those hosts work once the official repository merges the wiring. Source hosts launch through fabric-dsh (see the Installation section).