@sentropic/artifacts 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.2.8
+
+- Content hosts use a single UUID label: `https://<id>.<base>/` resolves server-side,
+  either an artifact id (serves its current release) or a release id (serves that
+  frozen version). `parseContentHost` now returns `{ kind: 'id', id }` for exactly one
+  UUID label and nothing else; the former `<id>.pinned.<base>` form, two-label hosts and
+  foreign bases do not route.
+- Unknown ids return a uniform 404: the artifact and release lookups always both run,
+  and "no such artifact" and "no such release" share the same response body and timing
+  class, without revealing which kind exists. Digest verification and the deny rules
+  (service workers, traversal) are unchanged.
+- One wildcard per base at the edge: the `*.pinned.<base>` TLS host and ingress rule are
+  removed from the prod and preprod artifact-content overlays. No legacy fallback; immo
+  handles 301 redirects for its old hosts on its side.
+- Rename decision (recorded): the `pinnedUrl` field is renamed to `versionUrl` in the
+  `publicationUrls` hook, the summary, versions and source-read outputs and the result
+  schema, now holding `https://<releaseId>.<base>/`. The converged contract allows the
+  rename: no consumer outside `packages/artifacts` references `pinnedUrl`/`stableUrl`
+  (verified by grep over ui/contracts/e2e/api/cluster-mesh), and every in-package
+  consumer is updated atomically in this release.
+
+## 0.2.7
+
+- Fix the `artifacts_get_source` wire payload that broke page editing in claude.ai:
+  files are no longer returned as a JSON integer array (`bytes: Array.from(bytes)`).
+  Text mime types (the canonical `TEXT_MIME_PATTERN`) come back as `text` with
+  `encoding: "utf8"`; every other file — including non-UTF-8 "text" — as `base64`
+  with `encoding: "base64"`. Size and digest verification still run on the raw
+  bytes before encoding. An 816-byte page now serializes to a few KiB instead of
+  blowing the tool-result budget.
+- `get_source` (and the conflict `currentSource`) no longer embeds any authoring
+  guide; the result carries only a `guideRef` (`{tool: "artifacts_get_api_guide",
+  version}`) naming the tool and version to fetch it from.
+- Per-call budgets are unchanged: at most 32 files and 262144 decoded bytes; the
+  2 MiB serialized MCP result budget still holds for the full snapshot.
+- Tool schema (`artifacts_get_source` description, v2 result schema source files),
+  the API guide text and the README source section describe the text/base64
+  encoding and the guide reference.
+
 ## 0.2.6
 
 - Integrate part 1 with the source reads, sharing, terminal deletion, masking and

package/README.md

@@ -386,8 +386,10 @@ a registrable domain. Assets within the same artifact origin remain loadable.
 - `src/content/grants.ts` — 55s HMAC content grants (60s cutoff budget) and
   single-use activation tickets bound to subject, artifact, exact release
   and channel (`stable` or `pinned`); secrets and clocks are injected.
-- `src/content/routing.ts` — stable (`<artifactId>.<base>`) and pinned
-  (`<releaseId>.pinned.<base>`) single-UUID origins; safe path resolution.
+- `src/content/routing.ts` — one wildcard per base with a single UUID label
+  `<id>.<base>`, resolved server-side as an artifact (current release) or a
+  release (frozen version); the former `<id>.pinned.<base>` form no longer
+  routes; safe path resolution.
 - `src/content/headers.ts` — no-store/nosniff/frame-denial/CSP headers and
   the host-only `__Host-artifacts_grant` cookie.
 - `src/content/handler.ts` — transport-free content serving: per-version
@@ -403,12 +405,14 @@ a registrable domain. Assets within the same artifact origin remain loadable.
   definition wrapper (the optional peer is required here and by the root barrel).
 
 Ticket issuance and redemption both require `subjectId`, `artifactId`,
-`releaseId` and `channel`. The handler checks the release resolved from the
-requested origin and its channel before minting a grant. A stable ticket
-issued for r1 cannot activate r2 after republish, and a stable ticket cannot
-activate a pinned origin (or vice versa). Mismatches return 401 without a
-grant cookie and preserve the ticket for a matching request. Tickets expire
-at `expiresAt` (120 seconds by default) and can be redeemed only once.
+`releaseId` and `channel`. The handler resolves the single UUID label
+server-side — an artifact id serves its current release, a release id serves
+that frozen version — and checks the resolved release and its channel before
+minting a grant. A stable ticket issued for r1 cannot activate r2 after
+republish, and a stable ticket cannot activate a release id (or vice versa).
+Mismatches return 401 without a grant cookie and preserve the ticket for a
+matching request. Tickets expire at `expiresAt` (120 seconds by default) and
+can be redeemed only once.
 
 ## First publish (bootstrap)
 
@@ -439,9 +443,13 @@ empty defaults. Existing profile selections remain explicit.
 
 `POST /get_source` accepts `artifactId`, optional `releaseId`, and optional unique
 `paths` (1–32 entries). Bind `publication.getRelease` and `sources.getSource` on
-the HTTP app. It returns the canonical manifest, verified author file bytes,
-and separate nullable `sourceRef`; readers need the distinct source permission.
-The snapshot is limited to 32 files and 262144 decoded bytes. Hosts must qualify
+the HTTP app. It returns the canonical manifest, verified author files, and a
+separate nullable `sourceRef`; readers need the distinct source permission.
+Size and digest are verified on the raw bytes, then each file is encoded for the
+wire: text mime types as `text` with `encoding: "utf8"`, all other files as
+`base64` with `encoding: "base64"` — never an integer array. The result carries
+a `guideRef` (`{tool, version}`) instead of the guide body. The snapshot is
+limited to 32 files and 262144 decoded bytes. Hosts must qualify
 a 2 MiB serialized MCP result budget before selecting this capability.
 
 `POST /set_access` grants or revokes a named principal's read access, requires a

package/dist/content/handler.js

@@ -1,13 +1,17 @@
 /**
- * L-5d — transport-free content handler (spec-v8 §9 5d). Serves raw
- * release bytes on the separate content domain (never HTML on the
- * control origin). Per-version activation: a single-use ticket redeemed
- * by the host-authenticated subject mints a short subject+artifact+
- * release grant as a host-only cookie. Every request re-verifies the
- * grant AND live ACL/lifecycle state, so withdrawal cuts readers at the
- * next request (inside the 60s budget, no cache reliance). Republish
- * demands fresh consent on the stable origin (401); pinned origins keep
- * their release. Unknown/unreadable → same 404; bad grants → 401.
+ * L-5d — transport-free content handler (owner decision relayed by immo).
+ * Serves raw release bytes on the separate content domain (never HTML on
+ * the control origin). One wildcard per base: the single UUID label
+ * `<id>.<base>` is resolved server-side — an artifact id serves its
+ * current release, a release id serves that frozen version; an unknown id
+ * gets the same 404 response and timing class whatever kind it would be.
+ * Per-version activation: a single-use ticket redeemed by the
+ * host-authenticated subject mints a short subject+artifact+release grant
+ * as a host-only cookie. Every request re-verifies the grant AND live
+ * ACL/lifecycle state, so withdrawal cuts readers at the next request
+ * (inside the 60s budget, no cache reliance). Republish demands fresh
+ * consent on an artifact id (401); a release id keeps its release.
+ * Unknown/unreadable → same 404; bad grants → 401.
  */
 import { errorBody } from '../http.js';
 import { CONTENT_GRANT_TTL_SECONDS } from './grants.js';
@@ -65,29 +69,36 @@ export function createContentHandler(deps) {
         const origin = parseContentHost(request.host, deps.baseDomain);
         if (origin === undefined)
             return fail(404);
+        // One label, resolved server-side: an artifact id serves its current
+        // release, a release id serves that frozen version. Both lookups
+        // always run, so an unknown id gets the same 404 and timing class
+        // whether it is a missing artifact or a missing release.
+        const [current, byRelease] = await Promise.all([
+            deps.publication.getCurrent(origin.id),
+            deps.publication.getRelease(origin.id),
+        ]);
         let artifactId;
         let release;
-        if (origin.kind === 'stable') {
-            artifactId = origin.artifactId;
-            release = await deps.publication.getCurrent(artifactId);
+        let channel;
+        if (current !== undefined) {
+            artifactId = origin.id;
+            release = current;
+            channel = 'stable';
         }
-        else {
-            release = await deps.publication.getRelease(origin.releaseId);
-            if (release === undefined)
-                return fail(404);
-            const owner = JSON.parse(release.manifest).artifactId;
-            if (typeof owner !== 'string')
-                return fail(404);
-            artifactId = owner;
+        else if (byRelease !== undefined) {
+            artifactId = byRelease.artifactId;
+            release = byRelease;
+            channel = 'pinned';
         }
-        if (release === undefined)
+        else {
             return fail(404);
+        }
         if (request.ticket !== undefined) {
             if (request.actorId === undefined || request.actorId.length === 0)
                 return fail(401);
             try {
                 await deps.tickets.redeem(request.ticket, {
-                    subjectId: request.actorId, artifactId, releaseId: release.releaseId, channel: origin.kind,
+                    subjectId: request.actorId, artifactId, releaseId: release.releaseId, channel,
                 });
             }
             catch {

package/dist/content/routing.d.ts

@@ -1,9 +1,6 @@
 export type ContentOrigin = {
-    kind: 'stable';
-    artifactId: string;
-} | {
-    kind: 'pinned';
-    releaseId: string;
+    kind: 'id';
+    id: string;
 };
 /** Parse a content Host header against the configured base domain. */
 export declare function parseContentHost(host: string, baseDomain: string): ContentOrigin | undefined;

package/dist/content/routing.js

@@ -1,11 +1,10 @@
 /**
- * L-5d — content routing (spec-v8 §9 5d).
- *
- * Two origins per artifact, each with a single UUID label: the stable
- * origin `<artifactId>.<base>` follows the current release; the pinned
- * origin `<releaseId>.pinned.<base>` serves one immutable release. Two
- * concatenated UUIDs, extra labels, foreign bases and non-UUID labels
- * never route. Paths normalize to manifest file paths with an
+ * L-5d — content routing (owner decision relayed by immo): one wildcard
+ * per base with a single UUID label `<id>.<base>`. The label is resolved
+ * server-side by the handler — an artifact id serves its current release,
+ * a release id serves that frozen version. The former `<id>.pinned.<base>`
+ * form, two labels, foreign bases and non-UUID labels never route (no
+ * legacy fallback). Paths normalize to manifest file paths with an
  * `index.html` default; traversal, empty segments, backslashes and
  * encoded traversal never resolve (no history fallback hiding missing
  * assets). Service workers are detectable so the handler can deny them.
@@ -21,10 +20,7 @@ export function parseContentHost(host, baseDomain) {
         return undefined;
     const labels = normalized.slice(0, normalized.length - base.length - 1).split('.');
     if (labels.length === 1 && isArtifactId(labels[0])) {
-        return { kind: 'stable', artifactId: labels[0] };
-    }
-    if (labels.length === 2 && labels[1] === 'pinned' && isArtifactId(labels[0])) {
-        return { kind: 'pinned', releaseId: labels[0] };
+        return { kind: 'id', id: labels[0] };
     }
     return undefined;
 }

package/dist/http.d.ts

@@ -51,10 +51,10 @@ export interface HttpAppDeps {
     acls: AclStore;
     lifecycle: Pick<LifecycleService, 'stateOf' | 'canRead' | 'getReleaseState'>;
     isApprovedAccount?: (principalId: string) => boolean;
-    /** One trusted URL policy shared by HTTP and MCP receipts. */
+    /** One trusted URL policy shared by HTTP and MCP receipts: the artifact page and the exact version page. */
     publicationUrls?: (artifactId: string, releaseId: string) => {
         stableUrl: string;
-        pinnedUrl: string;
+        versionUrl: string;
     };
 }
 export interface ArtifactApp {
@@ -64,7 +64,7 @@ export interface ArtifactApp {
     handle(request: HttpRequest, invocation: ArtifactInvocationContext): Promise<HttpResponse>;
 }
 /** Retained for consumers describing canonical textual publication inputs. */
-export declare const TEXT_MIME_PATTERN = "^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])";
+export { TEXT_MIME_PATTERN } from './server/mime.js';
 /** Other mutation surfaces need their own qualification before host activation. */
 export declare function assertArtifactsTransportProfile(value: unknown): asserts value is CompiledArtifactsProfile;
 export declare function createHttpArtifactApp(deps: HttpAppDeps): ArtifactApp;

package/dist/http.js

@@ -15,6 +15,8 @@ import { artifactSummary } from './server/summary.js';
 import { artifactVersions } from './server/versions.js';
 import { manageArtifact } from './server/management.js';
 import { createPostgresManagementUnit } from './adapters/postgres-management.js';
+import { TEXT_MIME_RE } from './server/mime.js';
+import { API_GUIDE_REF } from './server/templates.js';
 export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 /** Stable content-route error codes; private driver messages never leave the host. */
 export function errorBody(status) {
@@ -23,8 +25,7 @@ export function errorBody(status) {
             500: 'internal_error', 503: 'capability_unavailable' }[status] ?? 'internal_error' };
 }
 /** Retained for consumers describing canonical textual publication inputs. */
-export const TEXT_MIME_PATTERN = '^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])';
-const TEXT_MIME_RE = new RegExp(TEXT_MIME_PATTERN);
+export { TEXT_MIME_PATTERN } from './server/mime.js';
 function object(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
         throw new ArtifactProfileInputError();
@@ -160,11 +161,13 @@ export function createHttpArtifactApp(deps) {
         const files = (await readManifestFiles(release.manifest, invocation.storageScopeId)).filter(file => paths.has(file.path))
             .map(file => ({ path: file.path, mimeType: file.mimeType, size: file.bytes.byteLength,
             digest: entries.find(entry => entry.path === file.path).digest,
-            ...(file.text === undefined ? { bytes: Array.from(file.bytes) } : { text: file.text }) }));
+            ...(file.text === undefined
+                ? { base64: Buffer.from(file.bytes).toString('base64'), encoding: 'base64' }
+                : { text: file.text, encoding: 'utf8' }) }));
         await visible(artifactId, invocation, 'source');
         const failure = { ...outcome.failure, conflict: { ...conflict, currentSource: {
                     artifactId, releaseId: release.releaseId, digest: conflict.currentDigest, manifest: release.manifest,
-                    files, sourceRef: null, ...deps.publicationUrls?.(artifactId, release.releaseId),
+                    files, sourceRef: null, guideRef: API_GUIDE_REF, ...deps.publicationUrls?.(artifactId, release.releaseId),
                 } } };
         Object.defineProperty(failure, 'cause', { value: outcome.failure.cause, enumerable: false });
         return { ok: false, failure: Object.freeze(failure) };

package/dist/mcp-core.d.ts

@@ -10,7 +10,7 @@ export { createRadarKeyDerivation } from './server/command-identity.js';
 export type { ArtifactKeyDerivationBinding } from './server/command-identity.js';
 export declare const ARTIFACTS_PROVIDER_ID = "sentropic.artifacts";
 export declare const ARTIFACTS_APP_ID = "sentropic-artifacts";
-export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.6";
+export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.8";
 export declare const ARTIFACTS_TOOL_NAMES: readonly ["artifacts_get_template", "artifacts_get_api_guide", "artifacts_ensure", "artifacts_publish", "artifacts_create_upload", "artifacts_commit_upload", "artifacts_list", "artifacts_get", "artifacts_get_source", "artifacts_fork", "artifacts_set_access", "artifacts_promote", "artifacts_renew", "artifacts_delete", "artifacts_restore", "artifacts_list_versions", "artifacts_revert"];
 export type ArtifactsToolName = (typeof ARTIFACTS_TOOL_NAMES)[number];
 export declare const ARTIFACTS_TOOL_SPECS: {

package/dist/mcp-core.js

@@ -7,10 +7,13 @@ export * from './profile/index.js';
 export { createRadarKeyDerivation } from './server/command-identity.js';
 export const ARTIFACTS_PROVIDER_ID = 'sentropic.artifacts';
 export const ARTIFACTS_APP_ID = 'sentropic-artifacts';
-export const ARTIFACTS_PROVIDER_VERSION = '0.2.6';
+export const ARTIFACTS_PROVIDER_VERSION = '0.2.8';
 export const ARTIFACTS_TOOL_NAMES = ARTIFACT_CAPABILITY_NAMES;
 export const ARTIFACTS_TOOL_SPECS = ARTIFACTS_TOOL_NAMES.map((name) => ({ name,
-    description: `Artifacts ${name.slice('artifacts_'.length).replaceAll('_', ' ')}.`,
+    description: name === 'artifacts_get_source'
+        ? 'Artifacts get source: verified files of the current or a selected release as `text` (encoding "utf8") '
+            + 'or `base64` (encoding "base64"), never an integer array, plus a guideRef instead of the guide body.'
+        : `Artifacts ${name.slice('artifacts_'.length).replaceAll('_', ' ')}.`,
     mutability: (['artifacts_list', 'artifacts_get', 'artifacts_get_template', 'artifacts_get_api_guide',
         'artifacts_get_source', 'artifacts_list_versions'].includes(name) ? 'read-only' : name === 'artifacts_publish' ? 'append' : 'state-transition'),
 }));

package/dist/profile/schemas.js

@@ -86,7 +86,10 @@ export function capabilitySchema(name, profile) {
         case 'list_versions': return profile.resultEnvelopeVersion !== 2 ? idOnly : obj({ artifactId: id,
             limit: { ...integer(1, 100), default: 20 }, cursor: { ...str, maxLength: 4096 } }, ['artifactId']);
         case 'get_source': return obj({ artifactId: id, releaseId: id,
-            paths: { type: 'array', minItems: 1, maxItems: 32, items: { ...str, maxLength: profile.rules.pathMaxBytes } } }, ['artifactId']);
+            paths: { type: 'array', minItems: 1, maxItems: 32, items: { ...str, maxLength: profile.rules.pathMaxBytes },
+                description: 'Unique manifest paths; omit to read the whole snapshot (max 32 files, 256 KiB decoded). ' +
+                    'Result files are `text` with encoding "utf8" or `base64` with encoding "base64" (never an integer ' +
+                    'array), plus a guideRef; the guide body is never embedded.' } }, ['artifactId']);
         case 'delete': return obj({ artifactId: id, expectedCurrentReleaseId: { ...id, type: ['string', 'null'] },
             idempotencyKey: key, confirmationRef: { ...str, maxLength: 4096 } }, ['artifactId', 'idempotencyKey', ...(profile.requireExpectedCurrentReleaseId ? ['expectedCurrentReleaseId'] : [])]);
         case 'revert': {

package/dist/server/mime.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Canonical text-mime pattern shared by publication input rules and source
+ * reads. Leaf module: both `http.ts` and `server/source-read.ts` import it
+ * without an import cycle.
+ */
+export declare const TEXT_MIME_PATTERN = "^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])";
+export declare const TEXT_MIME_RE: RegExp;

package/dist/server/mime.js

@@ -0,0 +1,7 @@
+/**
+ * Canonical text-mime pattern shared by publication input rules and source
+ * reads. Leaf module: both `http.ts` and `server/source-read.ts` import it
+ * without an import cycle.
+ */
+export const TEXT_MIME_PATTERN = '^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])';
+export const TEXT_MIME_RE = new RegExp(TEXT_MIME_PATTERN);

package/dist/server/result-schema.js

@@ -7,11 +7,19 @@ const object = (properties, required = Object.keys(properties)) => ({
 const error = (code, details) => object({
     code: { enum: [code] }, message: string, retriable: { type: 'boolean' }, details,
 });
+/** get_source file: verified raw bytes encoded as UTF-8 text or base64, never an integer array. */
+const sourceFile = { type: 'object', additionalProperties: false,
+    properties: { path: string, mimeType: string, size: { type: 'integer', minimum: 0 }, digest: string,
+        encoding: { enum: ['utf8', 'base64'] }, text: string, base64: string },
+    required: ['path', 'mimeType', 'size', 'digest', 'encoding'],
+    oneOf: [{ required: ['text'], not: { required: ['base64'] } },
+        { required: ['base64'], not: { required: ['text'] } }] };
+const guideRef = object({ tool: string, version: string }, ['tool', 'version']);
 const pointer = object({ variant: { enum: ['pointer_conflict'] }, artifactId: string,
     expectedCurrentReleaseId: nullable, currentReleaseId: nullable, currentDigest: nullable,
     currentSource: object({ artifactId: string, releaseId: string, digest: nullable,
-        manifest: string, files: { type: 'array', items: { type: 'object' } }, sourceRef: { type: ['object', 'null'] },
-        stableUrl: string, pinnedUrl: string }, ['artifactId', 'releaseId', 'digest', 'manifest', 'files', 'sourceRef']),
+        manifest: string, files: { type: 'array', items: sourceFile }, sourceRef: { type: ['object', 'null'] },
+        guideRef, stableUrl: string, versionUrl: string }, ['artifactId', 'releaseId', 'digest', 'manifest', 'files', 'sourceRef', 'guideRef']),
 }, ['variant', 'artifactId', 'expectedCurrentReleaseId', 'currentReleaseId', 'currentDigest']);
 const common = { invocationId: string,
     commitState: { enum: ['not_committed', 'committed', 'unknown'] } };

package/dist/server/source-read.d.ts

@@ -9,7 +9,12 @@ export interface SourceReadPorts {
     getBlob(key: string): Promise<Uint8Array | undefined>;
     urls?: (artifactId: string, releaseId: string) => {
         stableUrl: string;
-        pinnedUrl: string;
+        versionUrl: string;
+    };
+    /** Guide reference returned instead of embedding the guide body. */
+    guideRef?: {
+        tool: string;
+        version: string;
     };
     maxFiles: number;
     maxTotalBytes: number;
@@ -22,17 +27,32 @@ export interface SourceReadInput {
 /** Read author bytes only. Provenance never substitutes for a stored snapshot. */
 export declare function readArtifactSource(ports: SourceReadPorts, input: SourceReadInput): Promise<{
     stableUrl?: string | undefined;
-    pinnedUrl?: string | undefined;
+    versionUrl?: string | undefined;
     artifactId: string;
     releaseId: string;
     digest: string;
     manifest: string;
-    files: {
-        bytes: number[];
+    files: ({
+        text: string;
+        encoding: "utf8";
+        path: string;
+        mimeType: string;
+        digest: string;
+        size: number;
+    } | {
+        base64: string;
+        encoding: "base64";
         path: string;
         mimeType: string;
         digest: string;
         size: number;
-    }[];
+    })[];
     sourceRef: SourceRef | null;
+    guideRef: {
+        readonly tool: "artifacts_get_api_guide";
+        readonly version: "v1";
+    } | {
+        tool: string;
+        version: string;
+    };
 }>;

package/dist/server/source-read.js

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto';
 import { parseManifest } from '../codecs.js';
 import { ArtifactOperationError } from './failures.js';
+import { TEXT_MIME_RE } from './mime.js';
+import { API_GUIDE_REF } from './templates.js';
 /** Read author bytes only. Provenance never substitutes for a stored snapshot. */
 export async function readArtifactSource(ports, input) {
     await ports.authorize();
@@ -59,10 +61,23 @@ export async function readArtifactSource(ports, input) {
             createHash('sha256').update(bytes).digest('hex') !== file.digest.slice(7)) {
             throw new ArtifactOperationError('verification_failed');
         }
-        files.push({ ...file, bytes: Array.from(bytes) });
+        // Verified raw bytes are encoded for the wire: text mime types as UTF-8
+        // text, everything else (including non-UTF-8 "text") as base64. Never an
+        // integer array, which blows the tool-result budget on small pages.
+        let text;
+        if (TEXT_MIME_RE.test(file.mimeType)) {
+            try {
+                text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch { /* Not valid UTF-8: fall back to base64. */ }
+        }
+        files.push({ ...file, ...(text !== undefined
+                ? { text, encoding: 'utf8' }
+                : { base64: Buffer.from(bytes).toString('base64'), encoding: 'base64' }) });
     }
     const sourceRef = await ports.getSource(input.artifactId) ?? null;
     await ports.authorize();
     return { artifactId: input.artifactId, releaseId: release.releaseId, digest: manifest.digest,
-        manifest: release.manifest, files, sourceRef, ...ports.urls?.(input.artifactId, release.releaseId) };
+        manifest: release.manifest, files, sourceRef, guideRef: ports.guideRef ?? API_GUIDE_REF,
+        ...ports.urls?.(input.artifactId, release.releaseId) };
 }

package/dist/server/summary.d.ts

@@ -10,7 +10,7 @@ export declare function artifactSummary(input: {
     };
     urls?: (artifactId: string, releaseId: string) => {
         stableUrl: string;
-        pinnedUrl: string;
+        versionUrl: string;
     };
     approved?: (principalId: string) => boolean;
 }): {
@@ -33,7 +33,7 @@ export declare function artifactSummary(input: {
     currentReleaseId: string | null;
     digest: string | null;
     stableUrl: string | null;
-    pinnedUrl: string | null;
+    versionUrl: string | null;
     title: string;
     description: string;
     icon: string | null;

package/dist/server/summary.js

@@ -8,7 +8,7 @@ export function artifactSummary(input) {
         storageScopeId: acl.storageScopeId, state, isPublic: acl.isPublic, withdrawn: state === 'withdrawn',
         createdAt: acl.createdAt ?? null, updatedAt: acl.updatedAt ?? null,
         currentReleaseId: current?.releaseId ?? null, digest: current ? parseManifest(current.manifest).digest ?? null : null,
-        stableUrl: urls?.stableUrl ?? null, pinnedUrl: current ? urls?.pinnedUrl ?? null : null,
+        stableUrl: urls?.stableUrl ?? null, versionUrl: current ? urls?.versionUrl ?? null : null,
         title: acl.metadata?.title ?? acl.title ?? acl.bindingName ?? artifactId,
         description: acl.metadata?.description ?? acl.description ?? '',
         icon: acl.metadata?.icon !== undefined ? acl.metadata.icon : acl.icon ?? null,

package/dist/server/templates.d.ts

@@ -29,5 +29,10 @@ export interface TemplateCatalogPort {
 }
 export declare const DEFAULT_TEMPLATE_ID = "static-html";
 export declare const DEFAULT_API_GUIDE_VERSION = "v1";
+/** Wire reference returned by get_source instead of embedding the guide body. */
+export declare const API_GUIDE_REF: {
+    readonly tool: "artifacts_get_api_guide";
+    readonly version: "v1";
+};
 /** Generic in-package catalog; hosts override with approved local assets. */
 export declare function createDefaultTemplateCatalog(): TemplateCatalogPort;

package/dist/server/templates.js

@@ -9,6 +9,8 @@
  */
 export const DEFAULT_TEMPLATE_ID = 'static-html';
 export const DEFAULT_API_GUIDE_VERSION = 'v1';
+/** Wire reference returned by get_source instead of embedding the guide body. */
+export const API_GUIDE_REF = { tool: 'artifacts_get_api_guide', version: DEFAULT_API_GUIDE_VERSION };
 const INDEX_HTML = [
     '<!doctype html>',
     '<html lang="en">',
@@ -66,7 +68,11 @@ const GUIDE_V1 = [
     '- `artifacts_list_versions`: full release history of one artifact —',
     '  per release: id, created at, author, state, whether it is current,',
     '  and a content digest.',
-    '- `artifacts_get_source`: current file contents (text decoded) for editing.',
+    '- `artifacts_get_source`: verified file contents of the current or a selected',
+    '  release, for editing. Text mime types come back as `text` with',
+    '  `encoding: "utf8"`; every other file as `base64` with `encoding: "base64"` —',
+    '  never an integer array. The result carries a `guideRef` (tool + version),',
+    '  never the guide body. Per call: at most 32 files and 256 KiB decoded.',
     '- `artifacts_revert`: make an earlier release current again as a NEW',
     '  release that copies its content — the artifact URL stays stable and',
     '  history only grows. Purged releases are refused with `release_unavailable`.',

package/dist/server/versions.d.ts

@@ -9,7 +9,7 @@ export declare function artifactVersions(input: {
     cursor?: string;
     state(releaseId: string): Promise<string>;
     urls?: (artifactId: string, releaseId: string) => {
-        pinnedUrl: string;
+        versionUrl: string;
     };
 }): Promise<{
     artifactId: string;
@@ -23,7 +23,7 @@ export declare function artifactVersions(input: {
         revertedFromReleaseId: string | null;
         digest: string;
         isCurrent: boolean;
-        pinnedUrl: string | null;
+        versionUrl: string | null;
     }[];
     nextCursor: string | null;
 }>;

package/dist/server/versions.js

@@ -29,7 +29,7 @@ export async function artifactVersions(input) {
             authorPrincipalId: release.authorPrincipalId ?? null, parentReleaseId: release.parentReleaseId ?? null,
             revertedFromReleaseId: release.revertedFromReleaseId ?? null, digest: release.manifestDigest,
             isCurrent: release.releaseId === input.currentReleaseId,
-            pinnedUrl: state === 'purged' ? null : input.urls?.(input.artifactId, release.releaseId).pinnedUrl ?? null };
+            versionUrl: state === 'purged' ? null : input.urls?.(input.artifactId, release.releaseId).versionUrl ?? null };
     }));
     const last = page.at(-1);
     const position = (value) => ({ createdAt: value.createdAt, releaseId: value.releaseId });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/artifacts",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Generic configurable artifacts MCP and artifact service: StorageScope/Artifact/Binding/Release model, canonical manifests, object authorization, idempotent intents (spec-v8 §9).",
   "type": "module",
   "license": "MIT",