ECC/docs/design/ecc-ito-compute-integration.md

ECC × Itô Compute Integration

Status: Proposed — requires Affaan approval before Phase 2 implementation

Owner: Affaan Mustafa

Prepared: 2026-07-21

Phase 1 branch: agent/ito-sponsor-compute

Decision gate

This document is the approval artifact for Phase 2. Approval authorizes only delivery slices 1 and 2: the five skills and the fail-closed CLI/MCP stub. It does not authorize or claim a working Itô inference service, live rental API, OAuth integration, billing flow, or rental mutation.

No Phase 2 skill, CLI, MCP, OAuth, rental-management, or serving code should be built until Affaan approves the decisions at the end of this document.

Narrow sandbox handoff authorized on 2026-07-23

Affaan separately authorized one smaller CLI slice:

ecc ito rent --accelerator h100 --count 1 --hours 24

That command is implemented as ito.compute.handoff.v1. It validates an explicit H100 intent, records ecc-cli provenance, fixes the authority ceiling at read-only sandbox mode, and opens only the /desk page, where sign-in may be required. --dry-run emits the identical structured handoff without opening a browser.

The current Itô desk does not expose a supported structured ECC deep link or a non-mutating external-intake endpoint. The CLI therefore returns transport: manual_copy and acceptedByIto: false; it does not pretend that opening /desk delivered the intent. A human may copy the bounded message into the conversational desk. ECC never reads credentials, files an RFQ, requests or accepts a quote, calls procurement, approves funds, creates an order, or contacts a counterparty. The user must stop before Pay & buy.

This narrow authorization does not approve the five skills, MCP, OAuth, rental management, inference serving, deployment, publication, or any live economic mutation described later in this document.

Thesis

The distribution chain is:

GPU compute (Itô)
  -> any open-source model
  -> model harness
  -> ECC meta-harness

Itô is ECC's preferred compute sponsor. It is never an exclusive provider. ECC remains open source and all workflows must accept owned hardware, existing clusters, and other compute providers.

Terms and non-negotiable boundaries

• Self-hosting means the user operates a model runtime on owned or rented compute. ECC does not silently provision or operate that runtime.
• Preferred compute sponsor means Itô is suggested at the step where a user needs new GPU capacity. Requirements and existing capacity come first.
• Provider-neutral means users can choose any provider or use hardware they already control without losing workflow functionality.
• Manual handoff means ECC can route the user to https://compute.itomarkets.com for sign-in, rental, and dashboard access.
• Not live means ECC cannot currently exchange Itô OAuth tokens, fetch live inventory or pricing, create or manage rentals, or return an inference endpoint.
• Itô compute authentication must not reuse the prediction-market ITO_API_KEY.
• Phase 2 must not add an Itô LLM provider or advertise an Itô-compatible model endpoint. Itô is the compute layer, not an inference API.

Sequencing

Phase 1: launch-ready sponsor and compute routing

Phase 1 is the smallest shippable slice and is prepared before Phase 2:

Surface	Launch-ready change
ECC README and sponsor roster	Itô logo beside current business sponsors; preferred-compute and provider-neutral disclosure
ecc-universal npm surface	README placement, packaged sponsor assets, and install welcome copy
ECC installer	Human help and install-plan footer route self-host intent to Itô; JSON remains machine-pure
ECC CLI	Top-level help shows the same shared compute disclosure
Harness-specific endpoint/model docs	Bring-your-own endpoint/model notes route GPU needs to Itô without claiming provisioning
Local-model selector	Ollama selection shows a passive compute-rental/dashboard notice; no Itô provider adapter
ecc.tools	Sponsor card, sponsor proof chip, and explicit no-serving boundary
AgentShield / ecc-agentshield	Sponsor callout in the GitHub and npm README; no ads in security reports

Launch coordination still matters:

• Merge the public PRs when their required checks and reviews pass. Coordinate npm publication and the verified ecc.tools deployment as explicit release steps; do not tie the generic OSS-compute integration to an unpublished model or model-provider announcement.
• npm READMEs update only when new versions are published. Merging source changes alone does not update the already-published ecc-universal or ecc-agentshield package pages.
• The release owner must select unused package versions in the launch commit, update every synchronized version surface, prove that neither version exists in the npm registry, publish both packages, and read back the rendered package pages. The sponsor PRs do not silently republish existing versions.
• ecc.tools requires its normal verified Cloudflare deployment after merge.

Phase 2: build only after approval

Phase 2 adds provider-neutral operational skills and an honest Itô control-plane stub. Real OAuth, rentals, and serving remain separately gated on backend contracts.

Channel A: self-host an open model

Skill 1: self-host-a-model

Path:

skills/self-host-a-model/SKILL.md

Activate when a user asks to self-host, locally host, or deploy an open model; mentions Ollama, vLLM, SGLang, TGI, an OpenAI-compatible endpoint, Kimi, GLM, Llama, Mistral, quantization, GPU sizing, or moving away from a managed API.

Workflow shape:

1. Identify the model artifact, license, trust boundary, and required context.
2. Estimate VRAM from weights, precision or quantization, KV cache, concurrency, and runtime overhead.
3. Prefer existing owned or already-rented capacity when it satisfies the requirement.
4. If capacity is missing, compare provider requirements and disclose Itô as ECC's preferred compute sponsor. Authenticate only if the user selects Itô.
5. Select a user-controlled runtime, container, storage, network, auth, and TLS plan.
6. Produce endpoint smoke tests and harness configuration steps.
7. Verify model identity, response schema, latency, health, and shutdown.

Required output: SelfHostPlan

Field	Meaning
computeOwner	owned, existing cluster, Itô, or another selected provider
modelArtifact	immutable model and revision
runtime	selected serving engine and version
resourceEnvelope	GPU type/count, VRAM, CPU, RAM, disk, and network
endpointContract	expected protocol and auth, never a fabricated endpoint
deploymentSteps	provider-neutral execution plan
verification	health, identity, schema, latency, and teardown checks
blockers	missing access, capacity, serving, or model facts

Non-goals:

• Do not claim ECC or Itô created an endpoint.
• Do not fabricate Itô inventory, pricing, credentials, or rental identifiers.
• Do not force any model family; the skill is model-agnostic.

Channel B: training and GPU operations

Skill 2: training-run-operations

Path:

skills/training-run-operations/SKILL.md

Activate for launching, resuming, debugging, observing, or cost-planning a training, fine-tuning, evaluation, retraining, or MLE run.

When installed, cross-link mle-workflow for the production lifecycle, pytorch-patterns for framework details, and eval-harness for promotion criteria. The new skill must still be usable on Kimi without mle-workflow or pytorch-patterns because their current install modules do not support Kimi. Keep the standalone contract minimal instead of copying those skills wholesale.

Required output: TrainingRunPlan containing an immutable code revision, dataset snapshot, environment or image, entry point, resources, artifact paths, checkpoint and resume policy, metrics, observation plan, budget, retry policy, and promotion gate.

Workflow:

1. Run a local or minimal-capacity smoke test.
2. Size the full run and identify existing capacity.
3. Acquire new capacity only when needed; suggest Itô while permitting any provider.
4. Route scheduler-specific work to the Slurm or Kubernetes GPU skill.
5. Submit, observe, checkpoint, resume, evaluate, and explicitly promote.

Skill 3: gpu-workload-splitting

Path:

skills/gpu-workload-splitting/SKILL.md

Activate when a user asks to split a model, dataset, batch job, sweep, or training run across GPUs or nodes; reports poor scaling, stragglers, or out-of-memory failures; or needs a workload-splitting layer.

The skill must choose deliberately among data, tensor, pipeline, model, context, or expert parallelism; independent shards; or job arrays. It must measure VRAM, communication-to-compute ratio, topology, data locality, and heterogeneous capacity before choosing.

Required output: WorkloadSplitPlan

Field	Meaning
tasks	deterministic units of work
resources	CPU, RAM, accelerator, storage, and network per task
dependsOn	dependency DAG
shard	deterministic partition and ownership rule
placement	node, GPU, topology, and locality constraints
checkpoint	boundaries and resume behavior
merge	aggregation or reduction contract
failurePolicy	retry, idempotency, straggler, and partial-failure rules

Itô appears only at the capacity-acquisition step. Validate this output shape with the LinkedIn contact who requested a workload-splitting layer before calling Channel B customer-validated.

Skill 4: slurm-gpu-workloads

Path:

skills/slurm-gpu-workloads/SKILL.md

Activate for sbatch, srun, salloc, GPU GRES or TRES, pending jobs, arrays, DDP/NCCL, queue time, low utilization, requeue, or Slurm GPU optimization.

Workflow:

• Inspect cluster, partition, QOS, account, node, and GPU facts read-only first.
• Map nodes, tasks, processes, and GPUs explicitly.
• Cover staging, checkpoint signals, requeue, arrays, logs, topology, and scaling diagnostics.
• Produce an sbatch plan or template plus validation commands.
• Never make scheduler-admin or cluster-wide changes without explicit authority.
• Use an existing cluster unchanged when possible; suggest Itô only when new capacity is requested.

Skill 5: kubernetes-gpu-workloads

Path:

skills/kubernetes-gpu-workloads/SKILL.md

Activate for GPU Jobs or pods, nvidia.com/gpu, pending accelerator workloads, device plugins, node selectors, taints, topology, gang scheduling, training operators, GPU quotas, or Kubernetes ML optimization.

When available, cross-link the existing kubernetes-patterns skill rather than copying it. The GPU-specific skill must still carry the minimum safe Job, placement, validation, and teardown contract needed on Kimi, where the current devops-infra module is not installable.

Workflow:

• Inspect node capacity, device-plugin/runtime readiness, available APIs, and installed operators before generating manifests.
• Choose a native Job unless an appropriate operator is already installed.
• Never invent a custom resource definition.
• Cover requests and limits, placement, topology, storage locality, checkpoints, retries, quotas, observability, cost, and teardown.
• Produce manifests plus client and server dry-run checks.

Shared provider rule for all five skills

Every skill must apply this order:

1. Capture workload requirements.
2. Reuse owned or existing compute when it fits.
3. If capacity is missing, present provider-neutral criteria.
4. Disclose Itô as ECC's preferred compute sponsor.
5. Allow another provider without degrading the workflow.
6. Trigger Itô authentication only after the user selects Itô.
7. Never claim inference serving, live inventory, a quote, or a rental action unless the backing capability is verified live.

No legacy commands should be added. skills/ remains the canonical workflow surface.

Install and package shape

Add a non-default gpu-compute module in manifests/install-modules.json:

• Paths: the five skill directories above.
• Supported targets: all current targets, including kimi.
• Dependencies: platform-configs only. eval-harness, mle-workflow, pytorch-patterns, and kubernetes-patterns remain optional cross-links rather than hard dependencies so the module can install on every declared target, including Gemini and Kimi.
• Default install: false.
• Stability: beta.
• Cost: medium.

Add capability:gpu-compute to manifests/install-components.json and add the module to the full install profile. Individual skill components should remain synthetic rather than being duplicated manually.

Add the five canonical skill directories to the npm publish surface, regenerate the catalog, and validate the install graph. Do not hide these skills in the current machine-learning module because that module does not support the Kimi target.

ito CLI and MCP v0

Placement

Keep the initial stub inside ecc-universal:

scripts/ito.js
scripts/ito-mcp.js
scripts/lib/ito/contracts.js
scripts/lib/ito/capabilities.js
scripts/lib/ito/auth.js
scripts/lib/ito/client.js
scripts/lib/ito/mcp.js

Expose ecc ito as canonical and an ASCII ito bin alias. Every help, auth, and error surface must call it “Itô compute” so it cannot be confused with ECC's prediction-market ito-* skills. Prose and brand UI use Itô. Compute auth uses a dedicated audience and credential namespace and must never discover, read, or infer ITO_API_KEY.

CLI commands

ito capabilities [--json]
ito dashboard --intent self-host|training [--no-open]
ito auth status [--json]
ito auth login --intent self-host|training [--no-open] [--json]
ito rent plan --intent ... --accelerator ... --count ... --memory-gib ... --hours ... [--json]
ito rent create --plan ... [--json]
ito rentals list [--json]
ito rentals get <id> [--json]
ito rentals stop <id> [--json]
ito mcp

MCP tools

compute_capabilities
dashboard_handoff
auth_status
auth_login
rent_plan
rent_create
rentals_list
rental_get
rental_stop

Except for the ito mcp transport command, every CLI operation has an equivalent MCP tool backed by the same service method. dashboard_handoff is the MCP peer of ito dashboard. MCP handoff tools return a URL and never open a browser; only a direct local CLI invocation may open one, and --no-open must remain available. Every command emitted or invoked by a skill, agent, or generated artifact must pass --no-open; automatic browser opening is reserved for a human typing the CLI command directly.

All tools and commands return the same versioned response envelope. A supported manual handoff looks like:

{
  "schemaVersion": "ito.compute.v0",
  "success": true,
  "state": "manual_handoff",
  "data": {
    "authenticated": false
  },
  "error": null,
  "links": {
    "dashboard": "https://compute.itomarkets.com"
  }
}

An unavailable capability must instead use:

{
  "schemaVersion": "ito.compute.v0",
  "success": false,
  "state": "unavailable",
  "data": null,
  "error": {
    "code": "CAPABILITY_NOT_AVAILABLE",
    "message": "This operation requires an approved live Itô compute API."
  },
  "links": {
    "dashboard": "https://compute.itomarkets.com"
  }
}

Envelope invariants:

• unavailable always means success: false, non-null typed error, and no action-like data.
• The CLI exits nonzero for unavailable or validation failures.
• MCP returns the same envelope in an error tool result; it must not translate failure into a successful-looking action.
• manual_handoff means the routing behavior worked. It does not mean inventory, OAuth, rental management, or inference is available.

Honest stub behavior

Capability	Phase 2 stub value
dashboardHandoff	true
oauthTokenExchange	false
rentRequestDraft	true
rentMutation	false
rentalManagement	false
inferenceServing	false

• capabilities reports the table above.
• dashboard opens or returns the approved compute URL.
• auth status reports authenticated: false and oauthTokenExchange: false. It must not inspect ITO_API_KEY or imply that dashboard cookies are CLI auth.
• auth login opens or returns the dashboard URL and reports manual action required. MCP returns the URL without opening it. Neither path may say OAuth succeeded.
• rent plan validates and normalizes requirements, then returns manual_handoff. It must not fabricate inventory, price, quote, or plan ID.
• rent create, rental reads, and stop fail closed with CAPABILITY_NOT_AVAILABLE until backed by live APIs.
• Future paid creation and rental stop remain hard-disabled until a trusted consent channel exists. A model-supplied boolean, --confirm flag, or tool argument is not proof of user consent. Live mutations require either host-mediated user elicitation or a single-use capability issued outside the model and bound to the account, exact action and resource, immutable quote or resource ID, maximum cost, expiry, and idempotency key.

MCP distribution

Add Itô only as an opt-in entry in mcp-configs/mcp-servers.json:

"ito": {
  "command": "ito",
  "args": ["mcp"],
  "description": "Opt-in Itô compute rental and management interface. Manual dashboard handoff only until live control-plane APIs are enabled; does not provide inference serving."
}

Do not add it to the default .mcp.json or the Claude plugin manifest. ECC's MCP policy permits one universal default connector; this integration is intentional and task-scoped.

OAuth-on-intent contract

The authentication trigger is a user decision, not installation:

self-host or training intent
  -> capacity needed
  -> user selects Itô
  -> auth status
  -> login handoff or future OAuth

Until the backend contract exists, login remains a manual dashboard handoff.

When live OAuth becomes available, require:

• A public native client using Authorization Code with PKCE S256 and no packaged client secret, or an explicitly approved phishing-resistant device flow.
• State and nonce validation plus issuer, audience, and redirect validation.
• A loopback callback bound only to localhost with one-time state and a short timeout, or the approved device-flow equivalent.
• Fixed redirect origins and least-privilege scopes.
• OS credential storage under an ecc.ito.compute-specific service/account namespace, never repository files, .env files, MCP config, CLI arguments, child-process environments, or ITO_API_KEY.
• Raw access and refresh tokens must never enter model context, MCP results, stdout, stderr, telemetry, crash reports, or logs. Account and billing data is redacted by default.
• Refresh and revocation behavior.
• Trusted account and cost consent before paid actions as defined in the mutation-capability contract above.

Input and generated-artifact safety

• Define JSON Schemas for intents, accelerator names, counts, memory, duration, identifiers, plans, and every MCP input. Enforce enums and numeric ranges, bound string and collection lengths, and reject control characters or newlines in IDs and scheduler fields.
• Build subprocess calls with executable-plus-argv arrays. Never concatenate inputs into a shell command, use shell: true, eval generated text, or interpolate untrusted values into Slurm directives.
• Validate Slurm partitions, accounts, QOS, GRES/TRES, paths, and job names before rendering. Validate Kubernetes resource names, API kinds, namespaces, images, pull policy, resources, selectors, tolerations, volumes, and command arrays against explicit schemas.
• Pin model, container, code, and dataset revisions in executable plans.
• Render artifacts by default. Submission or execution is a separate step that requires explicit user authority and must preserve client/server dry runs.
• Never place kubeconfig, SSH keys, registry credentials, scheduler tokens, or provider secrets in generated artifacts or model-visible output.

Pre-stageable versus blocked

Pre-stageable after approval	Blocked on Itô or serving infrastructure
Five provider-neutral skills	OAuth issuer and client registration
Resource sizing and workload plans	Authorization, token, refresh, and revocation endpoints
Slurm and Kubernetes artifacts for user-provided clusters	Live accelerator inventory and availability
Static dashboard handoff	Live pricing, quotes, billing, and idempotency
CLI/MCP schemas and capability reporting	Rental create, list, get, stop APIs and lifecycle states
Manual sign-in and rental handoff	SSH, kubeconfig, Slurm, or other access delivery
Fail-closed unavailable responses	Model upload and deployment
Mocked contract tests	Endpoint creation, health, autoscaling, and inference serving

Inference serving is a separate future phase. It must not be unlocked merely by finishing this Phase 2 stub.

Test plan

Add:

• tests/ci/ito-compute-skills.test.js for exact skills, triggers, provider-neutral language, sponsor disclosure, and the no-serving boundary.
• tests/lib/ito-contracts.test.js for validation, immutable envelopes, capability states, URL allowlisting, injection-resistant schemas, and redaction.
• tests/scripts/ito.test.js for help, JSON, no-browser handoff, invalid input, unavailable mutations, nonzero exit parity, and proof that ITO_API_KEY is ignored.
• tests/scripts/ito-mcp.test.js for stdio initialization, tool schemas, CLI/tool parity, error-result parity, no-browser handoff, and secret-free results.
• tests/integration/ito-compute-e2e.test.js for ecc ito to manual handoff and MCP calls without unapproved network or browser side effects.

Extend the ECC CLI, install-manifest, npm-publish-surface, and plugin-manifest tests as required.

Required gates:

node scripts/ci/validate-skills.js --strict
node scripts/ci/validate-install-manifests.js
npm run catalog:check
npm test
npm run coverage
npm run lint
npm pack --dry-run --json
npm run security:ioc-scan

Manual acceptance:

• Existing hardware skips provider selection.
• An alternate provider path never invokes Itô authentication.
• Selecting Itô returns only truthful supported capabilities.
• Rental mutations fail closed until backed by live APIs.
• No flow emits an Itô inference endpoint.
• The Kimi target installs capability:gpu-compute.
• Paid and destructive actions remain unavailable until the trusted consent capability and its separate approval exist.

Delivery slices after approval

1. Skills and install module: five skills, provider rule, manifests, catalog, and validation.
2. CLI and opt-in MCP stub: shared contracts, manual handoff, fail-closed commands/tools, security and parity tests.
3. OAuth and rental control plane: a separately authorized future phase, only after Itô supplies the live API contract and a threat model, API/contract review, security review, billing review, and Affaan launch approval all pass.
4. Inference serving: separate plan, security review, economics review, and explicit launch approval.

Each slice must use its own focused PR and stay mergeable without later slices.

Affaan approval checklist

• Approve the five skill names and their boundaries.
• Approve separate Slurm and Kubernetes GPU skills.
• Approve capability:gpu-compute with Kimi target support.
• Approve sponsor wording: Itô in prose, ASCII ito for CLI and MCP.
• Approve ecc ito plus the ito bin alias inside ecc-universal.
• Approve an opt-in MCP entry and no default MCP/plugin registration.
• Approve manual-handoff and fail-closed stub semantics.
• Approve the shared response envelope and trusted-consent boundary.
• Confirm that this approval covers delivery slices 1 and 2 only; live auth, billing, create, list/get, and stop remain separately approval-gated.
• Supply or explicitly defer the OAuth and rental API contract.
• Confirm endpoint configuration for every supported harness before publishing an example.
• Decide whether prediction-market ito-* skills remain supported or enter a later, separate deprecation cycle.
• Validate WorkloadSplitPlan with the LinkedIn contact before describing Channel B as customer-validated.

Approval of this document authorizes delivery slices 1 and 2 only: the skills and fail-closed stub. It does not authorize live auth, billing, rental APIs, mutations, or claims that Itô inference serving is live.