feat(artifacts): publish provider sdk

Move the host-neutral Artifact wire model and external Provider contract into @qoder-ai/harness/artifacts, then let Studio accept explicitly injected, fingerprint-bound Providers. Keep React, HTTP, activation, CSP, and iframe ownership in Studio, and make numeric compile budgets bounded host policy without expanding package imports.

The accepted spec is docs/specs/2026-08-22-artifact-provider-sdk-and-structurizr.md. Validation includes the serial npm run check gate, package dry-runs, and the cross-repository Structurizr catalog/snapshot/resource/viewer smoke.

Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>

Author: phodal

docs/adrs/studio-artifact-runtime-and-providers.md

@@ -15,6 +15,7 @@
   - [Render SVG and Mermaid artifacts through the React preview runtime](../specs/2026-08-22-studio-react-document-artifacts.md)
   - [Keep Walnut bootstrap receipts portable across platforms](../specs/2026-08-21-walnut-cross-platform-paths.md)
   - [Implement external Artifact providers in Harness Studio](../specs/2026-08-22-studio-external-artifact-provider-runtime.md)
+  - [Extract the Artifact provider SDK and prove it with Structurizr](../specs/2026-08-22-artifact-provider-sdk-and-structurizr.md)
 
 ## Context
 
@@ -175,12 +176,16 @@ type ArtifactSurfaceBinding =
   | { kind: "unavailable"; reason: string };
 ```
 
-All TypeScript shapes in this ADR are conceptual ownership contracts until a
-dated implementation spec freezes their internal names and validators; they are
-not a new public package API. The current V2 catalog may continue to project
-them through `backing`, `build`, and `renderer`. A later wire-format revision is
-justified only when a client needs information that cannot be represented
-safely and additively.
+The host-neutral descriptor, snapshot, source-entry, adapter, surface, and
+external Provider shapes are a public package API under
+`@qoder-ai/harness/artifacts`. Studio keeps compatibility re-exports while the
+core subpath is their sole source owner. React views, catalog discovery and
+classification, HTTP routes, activation storage, provider selection, compile
+execution, CSP, and iframe hosting stay in `@qoder-ai/harness-studio`; they are
+not SDK abstractions. The current V2 catalog continues to project the public
+contract through `backing`, `build`, and `renderer`. A later wire-format
+revision is justified only when a client needs information that cannot be
+represented safely and additively.
 
 The V2 compatibility projection is explicit:
 
@@ -253,6 +258,13 @@ executes the selected contribution and enforces project, dependency, time, and
 output bounds. Adding an SVG-like virtual document edits the build-runtime
 composition, not the compiler implementation.
 
+Numeric compile limits are Studio host policy. An embedder may lower them or
+raise them within Studio-owned hard ceilings; the effective policy participates
+in cache and build identity. Package permissions are not a numeric limit and
+remain owned by the selected trusted build-runtime contribution. A Provider
+that needs repository libraries performs a declared adapter transform instead
+of granting artifact-authored source arbitrary workspace imports.
+
 Build and snapshot identities include the source revision, adapter or build
 runtime id and version, schema version, and any external provider fingerprint
 that can affect output. Cache hits therefore cannot cross a meaningful runtime
@@ -550,24 +562,26 @@ must show that compare or replay is unavailable.
 
 ### Keep ownership narrow and discoverable
 
-Current source ownership remains:
+Current source ownership is:
 
 | Concern | Owner |
 | --- | --- |
-| Browser-safe catalog, descriptor, snapshot, and build protocols | `packages/harness-studio/src/artifact-model.ts` |
+| Host-neutral descriptor, snapshot, source-entry, adapter, surface, and Provider contracts | `packages/harness/src/artifacts/`, published as `@qoder-ai/harness/artifacts` |
+| Browser-safe compatibility re-export | `packages/harness-studio/src/artifact-model.ts` |
 | Directory discovery, classification, revision hashing, and catalog projection | `packages/harness-studio/src/server/artifact-catalog.ts` |
-| Adapter/build/plugin contracts and ordered server selection | `packages/harness-studio/src/server/artifact-adapter-contract.ts` and `artifact-plugin-registry.ts` |
+| Ordered server selection, receipt verification, activation, and embedded Provider injection | `packages/harness-studio/src/server/artifact-plugin-registry.ts`, `artifact-provider-discovery.ts`, and `artifact-provider-activation.ts` |
 | Format parsing and semantic projection | Format-owned adapter modules such as `pptx-artifact-adapter.ts` and `markdown-artifact-adapter.ts` |
 | Studio compile/build lifecycle | `artifact-build-runtimes.ts` and `artifact-compile-runtime.ts` |
 | Browser renderer composition | `packages/harness-studio/src/app/ArtifactView.tsx` |
 | Opaque-origin Studio preview lifecycle | `packages/harness-studio/src/app/ArtifactPreviewHost.tsx` |
 | External acquisition and verification | Provider-owned server modules, currently `packages/harness-studio/src/server/artifact-viewers.ts`, `qoder-canvas-viewer-bridge.ts`, and `walnut-bootstrap.ts` |
 
-The first external-provider implementation spec will choose the exact module
-split. It must move vendor translation and execution behind a provider-owned
-boundary rather than creating a global service locator. Core catalog, common
-server routes, and browser mounting must not gain another vendor branch when a
-provider is added.
+External-provider implementations keep vendor translation and execution behind
+a provider-owned boundary rather than creating a global service locator. An
+embedding application supplies installed Providers explicitly to server
+startup; activation still binds one contribution, fingerprint, lane, matcher,
+adapter profile, and surface profile. Core catalog, common server routes, and
+browser mounting do not gain another vendor branch when a provider is added.
 
 After that migration, `artifact-plugin-registry.ts` is the server composition
 root: a `createArtifactPluginRegistry({ builtIns, externalProviders })`-shaped

docs/specs/2026-08-22-artifact-provider-sdk-and-structurizr.md

@@ -0,0 +1,74 @@
+# Artifact provider SDK and Structurizr integration
+
+## Traceability
+
+- Spec ID: artifact-provider-sdk-and-structurizr
+- Status: Accepted
+
+## Intent
+
+Expose the host-neutral Artifact descriptor, snapshot, and external Provider
+contracts from `@qoder-ai/harness` so a repository can implement one Provider
+without importing Studio server internals. Keep Studio responsible for catalog
+HTTP routes, activation, provider selection, sandbox policy, and React UI. Prove
+the boundary with a local Structurizr DSL Provider before publishing the SDK and
+Studio packages.
+
+## Acceptance Scenarios
+
+- AC-1: `@qoder-ai/harness/artifacts` exports the Artifact wire model, source
+  entry, adapter/runtime bindings, Provider contract, and an inference helper;
+  the subpath imports no React or Studio server module.
+- AC-2: Harness Studio consumes the shared contract without changing its V2
+  catalog/snapshot wire format and accepts explicitly injected Providers through
+  `HarnessStudioServerOptions`; fingerprint-bound activation remains required.
+- AC-3: Studio's numeric source-file, source-byte, output-byte, and timeout
+  budgets are an explicit host policy with bounded overrides. Effective limits
+  participate in build/cache identity. Package imports remain restricted to the
+  selected trusted build runtime.
+- AC-4: Structurizr4js provides an experimental-local `.dsl` contribution using
+  the published SDK shape, runs parsing/layout in a bounded child process, and
+  renders the generated SVG through Studio's common opaque-origin hosted
+  surface. A cross-repository test exercises catalog, snapshot, resource, and
+  viewer routes.
+- AC-5: focused tests, package dry-runs, the serial Better Harness checks, and
+  Structurizr provider tests pass before publication. Publication uses the
+  repository's GitHub Actions workflow; registry reads and a clean-consumer
+  install verify the released versions separately from local tests.
+
+## Non-goals
+
+- Moving `ArtifactView`, React renderers, HTTP routing, iframe policy, or
+  activation storage into `@qoder-ai/harness`.
+- Allowing artifact-authored code to import arbitrary workspace or npm packages.
+- Claiming the first Structurizr Provider is reviewed, remotely sandboxed, or a
+  general provider marketplace/discovery mechanism.
+- Publishing the Structurizr Provider package in this change.
+
+## Plan and Tasks
+
+1. Move the host-neutral contracts to a public `artifacts` subpath and keep
+   Studio compatibility re-exports while internal imports migrate.
+2. Add explicit embedded-provider injection, provider receipt/fingerprint
+   validation, public activation helpers, and configurable bounded compile
+   limits to Studio.
+3. Add the Structurizr Provider package, child driver, hosted SVG surface, and
+   focused tests in structurizr4js.
+4. Run focused and package checks in both repositories, then run Better Harness
+   generated/Harness/UI/Studio checks serially.
+5. Perform Review Readiness Check, commit exact paths, push, dispatch releases,
+   and verify npm plus a clean consumer.
+
+## Test and Review Evidence
+
+- AC-1/AC-2: Harness and Studio TypeScript builds plus Artifact provider,
+  activation, registry, catalog, and server focused Vitest files.
+- AC-3: compile-runtime tests cover custom accepted limits, hard-ceiling
+  rejection, and cache/build identity separation.
+- AC-4: Structurizr Provider tests cover valid DSL, invalid DSL, exact revision
+  envelope/resource identity, hosted document safety, and real Studio routes.
+- AC-5: `npm pack --dry-run --json` for both packages, serial workspace checks,
+  GitHub Actions run URLs, `npm view`, and an isolated install/import receipt.
+- Risk: provider code is trusted local code. The initial contribution therefore
+  stays `experimental-local`, uses `trusted-local-process`, and never weakens the
+  opaque-origin surface or artifact-authored package allowlist.

package-lock.json

@@ -71,6 +71,38 @@ only by Run. Other providers, including versioned document or presentation
 systems, can inject the same server adapter interface without adopting the
 catalog's storage format.
 
+An embedding application can install an Artifact Provider implemented against
+`@qoder-ai/harness/artifacts`, activate one exact fingerprint-bound
+contribution, and inject it explicitly:
+
+```ts
+import {
+  activateArtifactContribution,
+  startHarnessStudioServer,
+} from "@qoder-ai/harness-studio";
+
+await activateArtifactContribution(
+  provider,
+  "my-format",
+  "external-fallback",
+  { extensions: ["my-format"] },
+  { root: stateRoot },
+);
+
+await startHarnessStudioServer({
+  appDir,
+  artifactDirectory,
+  artifactProviderStateRoot: stateRoot,
+  artifactProviders: [provider],
+  artifactCompileLimits: { maxSourceFiles: 128 },
+});
+```
+
+Numeric compile limits may be adjusted only within Studio's hard ceilings and
+are part of build/cache identity. They do not expand the package allowlist.
+Injected Provider receipts are fingerprint-checked, and an inactive or changed
+fingerprint never enters selection.
+
 ## Architecture
 
 ```text

packages/harness-studio/README.md

@@ -41,7 +41,7 @@
   "dependencies": {
     "@phosphor-icons/react": "^2.1.10",
     "@pierre/diffs": "^1.3.5",
-    "@qoder-ai/harness": "0.1.0",
+    "@qoder-ai/harness": "0.2.0",
     "@qoder-ai/harness-ui": "0.1.0",
     "@shikijs/core": "^4.4.3",
     "@shikijs/engine-javascript": "^4.4.3",