superbee 0.4.3-pre.2 → 0.4.3-pre.3

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target3) => (target3 = mod != null ? __create(__
 var define_SUPERBEE_BUILD_IDENTITY_default;
 var init_define_SUPERBEE_BUILD_IDENTITY = __esm({
   "<define:__SUPERBEE_BUILD_IDENTITY__>"() {
-    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.3-pre.2" }, source: { commit: "9a0a564d4096ec7fe51a7f337e7e001542e8e6d5", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
+    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.3-pre.3" }, source: { commit: "11561dfb62d36f61149e2655e8bebeb08c4e7c9f", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -22730,7 +22730,13 @@ async function discoverIssuer(fetchImpl, issuer) {
   throw lastError instanceof CliError ? lastError : new CliError("RUNTIME", `could not read issuer metadata for ${issuer}`);
 }
 async function discoverHosted(fetchImpl, target3) {
-  const prm = await fetchJson(fetchImpl, target3.metadataUrl, "protected-resource metadata");
+  let prm;
+  try {
+    prm = await fetchJson(fetchImpl, target3.metadataUrl, "protected-resource metadata");
+  } catch (error51) {
+    if (error51 instanceof CliError && error51.details?.status === 404) throw missingMetadataError(target3);
+    throw error51;
+  }
   const resource = optionalString(prm.resource);
   if (resource === void 0) {
     throw new CliError("RUNTIME", `protected-resource metadata at ${target3.metadataUrl} has no resource`);
@@ -22774,13 +22780,93 @@ function resolveClientId(sources) {
     details
   });
 }
-var DEFAULT_RESOURCE_PATH, PUBLISHED_CLIENT_ID_FIELD, BUILT_IN_CLIENT_IDS, REQUESTED_SCOPE, HTTP_TIMEOUT_MS, CLIENT_ID, MAX_METADATA_BYTES;
+function parentDomain(hostname5) {
+  if (hostname5.startsWith("[") || IPV4.test(hostname5)) return null;
+  const labels = hostname5.split(".");
+  if (labels.length < 3 || labels.some((label) => label === "")) return null;
+  return labels.slice(1).join(".");
+}
+function mayBeWorkspaceOrigin(target3) {
+  const url2 = new URL(target3.origin);
+  return url2.protocol === "https:" && url2.port === "" && target3.audience === `${target3.origin}${DEFAULT_RESOURCE_PATH}` && parentDomain(url2.hostname) !== null;
+}
+function trustedPointerTarget(origin, resource) {
+  if (typeof resource !== "string" || resource.length > MAX_POINTER_RESOURCE_LENGTH || resource.includes("@")) return null;
+  let from;
+  let to;
+  try {
+    from = new URL(origin);
+    to = new URL(resource);
+  } catch {
+    return null;
+  }
+  if (from.protocol !== "https:" || to.protocol !== "https:") return null;
+  if (to.username || to.password || to.port !== "" || from.port !== "" || to.search || to.hash) return null;
+  if (to.hostname === from.hostname) return null;
+  const parent = parentDomain(from.hostname);
+  if (parent === null || to.hostname !== `mcp.${parent}`) return null;
+  try {
+    return resolveHostedTarget(resource);
+  } catch {
+    return null;
+  }
+}
+function missingMetadataError(target3) {
+  const hostname5 = new URL(target3.origin).hostname;
+  const parent = parentDomain(hostname5);
+  const label = hostname5.split(".")[0];
+  const suggestion = parent !== null && label !== "mcp" && isWorkspaceSlug(label) ? { host: `https://mcp.${parent}`, workspace: label } : null;
+  return new CliError("RUNTIME", `protected-resource metadata at ${target3.metadataUrl} returned HTTP 404`, {
+    details: {
+      status: 404,
+      reason: "no_protected_resource_metadata",
+      host: target3.origin,
+      ...suggestion ? { suggested_host: suggestion.host, suggested_workspace: suggestion.workspace } : {}
+    },
+    help: suggestion ? `${target3.origin} may be a workspace address rather than the sign-in host; if so, re-run with --host ${commandToken(suggestion.host)} --workspace ${commandToken(suggestion.workspace)} (--workspace only where the command takes it)` : `${target3.origin} publishes no Superbee sign-in metadata; check the URL, or ask the host's operator which Superbee host to use`
+  });
+}
+async function readWorkspacePointer(fetchImpl, target3) {
+  let pointer;
+  try {
+    pointer = await fetchJson(fetchImpl, `${target3.origin}${WORKSPACE_POINTER_PATH}`, "workspace pointer");
+  } catch {
+    return null;
+  }
+  if (pointer.schema_version !== 1 || !isWorkspaceSlug(pointer.workspace_slug)) return null;
+  if (pointer.workspace_slug !== new URL(target3.origin).hostname.split(".")[0]) return null;
+  const gateway = trustedPointerTarget(target3.origin, pointer.resource);
+  if (gateway === null) return null;
+  return { target: gateway, workspaceSlug: pointer.workspace_slug, requestedOrigin: target3.origin };
+}
+async function followWorkspaceOrigin(fetchImpl, target3) {
+  if (!mayBeWorkspaceOrigin(target3)) return null;
+  let status2;
+  try {
+    const response = await fetchImpl(target3.metadataUrl, {
+      headers: { accept: "application/json" },
+      redirect: "error",
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
+    });
+    status2 = response.status;
+    await response.body?.cancel().catch(() => void 0);
+  } catch {
+    return null;
+  }
+  if (status2 !== 404) return null;
+  const followed = await readWorkspacePointer(fetchImpl, target3);
+  if (followed === null) throw missingMetadataError(target3);
+  return followed;
+}
+var DEFAULT_RESOURCE_PATH, PUBLISHED_CLIENT_ID_FIELD, BUILT_IN_CLIENT_IDS, REQUESTED_SCOPE, HTTP_TIMEOUT_MS, CLIENT_ID, MAX_METADATA_BYTES, WORKSPACE_POINTER_PATH, IPV4, MAX_POINTER_RESOURCE_LENGTH;
 var init_discovery = __esm({
   "../cli/src/hosted-auth/discovery.ts"() {
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
     init_errors4();
+    init_command_text();
+    init_reference();
     DEFAULT_RESOURCE_PATH = "/mcp";
     PUBLISHED_CLIENT_ID_FIELD = "superbee_cli_client_id";
     BUILT_IN_CLIENT_IDS = Object.freeze({});
@@ -22788,6 +22874,9 @@ var init_discovery = __esm({
     HTTP_TIMEOUT_MS = 1e4;
     CLIENT_ID = /^[\x21-\x7e]{1,256}$/;
     MAX_METADATA_BYTES = 256 * 1024;
+    WORKSPACE_POINTER_PATH = "/.well-known/superbee-workspace";
+    IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+    MAX_POINTER_RESOURCE_LENGTH = 2048;
   }
 });
 
@@ -23010,8 +23099,11 @@ __export(session_exports, {
   readPending: () => readPending,
   readSession: () => readSession,
   requireHostedBundleHost: () => requireHostedBundleHost,
+  resolveHostChoice: () => resolveHostChoice,
+  resolveHostChoiceOrNull: () => resolveHostChoiceOrNull,
   resolveHostSelection: () => resolveHostSelection,
   resolveHostSelectionOrNull: () => resolveHostSelectionOrNull,
+  resolveNamedHost: () => resolveNamedHost,
   sessionAccount: () => sessionAccount,
   sessionDirFor: () => sessionDirFor,
   storeForNewSession: () => storeForNewSession,
@@ -23022,6 +23114,8 @@ __export(session_exports, {
   waitForHostedSignIn: () => waitForHostedSignIn,
   waitingSignIns: () => waitingSignIns,
   withSessionLock: () => withSessionLock,
+  workspaceForNamedHost: () => workspaceForNamedHost,
+  workspaceOriginView: () => workspaceOriginView,
   writeDefaultHost: () => writeDefaultHost
 });
 import { mkdir as mkdir2, readdir as readdir3, realpath as realpath2, stat as stat3, unlink as unlink5 } from "node:fs/promises";
@@ -23125,10 +23219,31 @@ function notSignedInError(env = {}) {
     { details: { status: "not_signed_in", reason: "no_host", sign_in_command: command }, help: command }
   );
 }
-async function requireHostedBundleHost(flag, home2, env = {}) {
-  const chosen = await hostedBundleHost(flag, home2);
-  if (!chosen) throw notSignedInError(env);
-  return resolveHostedTarget(chosen);
+async function requireHostedBundleHost(flag, deps) {
+  if (flag && deps.fetch !== null) return resolveNamedHost(flag, { home: deps.home, fetch: deps.fetch });
+  const chosen = await hostedBundleHost(flag, deps.home);
+  if (!chosen) throw notSignedInError(deps.env);
+  return { target: resolveHostedTarget(chosen), workspaceSlug: null, requestedOrigin: null };
+}
+async function resolveNamedHost(host, deps) {
+  const target3 = resolveHostedTarget(host);
+  const plain = { target: target3, workspaceSlug: null, requestedOrigin: null };
+  if (await readSession(deps.home, target3) || await readPending(deps.home, target3)) return plain;
+  const followed = await followWorkspaceOrigin(deps.fetch, target3);
+  if (!followed) return plain;
+  return { target: followed.target, workspaceSlug: followed.workspaceSlug, requestedOrigin: followed.requestedOrigin };
+}
+function workspaceOriginView(named) {
+  if (named.requestedOrigin === null || named.workspaceSlug === null) return {};
+  return { host_from: "workspace-origin", requested_host: named.requestedOrigin, workspace_slug: named.workspaceSlug };
+}
+function workspaceForNamedHost(named, flag) {
+  if (named.workspaceSlug === null) return flag;
+  if (flag === void 0 || flag === named.workspaceSlug) return named.workspaceSlug;
+  throw new CliError("USAGE", `--host ${commandToken(named.requestedOrigin ?? "")} is the address of workspace '${named.workspaceSlug}', but --workspace names '${flag}'`, {
+    details: { reason: "workspace_conflict", host_workspace: named.workspaceSlug, workspace: flag },
+    help: `drop --workspace to use '${named.workspaceSlug}', or pass the other workspace's own address (or its slug) instead`
+  });
 }
 async function storedSessionHosts(home2) {
   const root = hostedAuthRoot(home2);
@@ -23177,6 +23292,8 @@ function hostSourceText(source) {
   switch (source) {
     case "flag":
       return "--host";
+    case "workspace-origin":
+      return "the gateway the workspace address in --host points to";
     case "last-sign-in":
       return "your last sign-in, the only host with a session";
     case "only-session":
@@ -23185,11 +23302,14 @@ function hostSourceText(source) {
       return "your last sign-in; no session for it now";
   }
 }
-async function hostedWriteHost(flag, home2, retry) {
+async function hostedWriteHost(flag, home2, retry, fetchImpl) {
   if (flag !== void 0) {
     if (flag.trim() === "") throw new CliError("USAGE", "--host is empty: name the hosted Superbee URL", { help: retry("<url>") });
-    return { target: resolveHostedTarget(flag), source: "flag" };
+    if (fetchImpl === null) return { target: resolveHostedTarget(flag), source: "flag", workspaceSlug: null, requestedOrigin: null };
+    const named = await resolveNamedHost(flag, { home: home2, fetch: fetchImpl });
+    return { ...named, source: named.requestedOrigin !== null ? "workspace-origin" : "flag" };
   }
+  const unnamed = { workspaceSlug: null, requestedOrigin: null };
   const remembered = await readDefaultHost(home2);
   const stored = await storedSessionHosts(home2);
   const candidates = new Set(stored);
@@ -23213,22 +23333,30 @@ async function hostedWriteHost(flag, home2, retry) {
       help: `re-run with --host set to the host you mean (one of: ${hosts.join(", ")}); the last sign-in is not used when sessions are held for more than one host or it has none`
     });
   }
-  if (rememberedHost) return { target: resolveHostedTarget(rememberedHost), source: stored.length === 0 ? "last-sign-in-signed-out" : "last-sign-in" };
-  if (stored.length === 1) return { target: resolveHostedTarget(stored[0]), source: "only-session" };
+  if (rememberedHost) return { target: resolveHostedTarget(rememberedHost), source: stored.length === 0 ? "last-sign-in-signed-out" : "last-sign-in", ...unnamed };
+  if (stored.length === 1) return { target: resolveHostedTarget(stored[0]), source: "only-session", ...unnamed };
   return null;
 }
+async function resolveHostChoiceOrNull(flag, deps) {
+  const named = flag ?? (deps.env[HOST_ENV] || void 0);
+  if (named !== void 0) return resolveNamedHost(named, deps);
+  const remembered = await readDefaultHost(deps.home);
+  return remembered ? { target: resolveHostedTarget(remembered), workspaceSlug: null, requestedOrigin: null } : null;
+}
 async function resolveHostSelectionOrNull(flag, deps) {
-  const chosen = flag ?? (deps.env[HOST_ENV] || void 0) ?? await readDefaultHost(deps.home) ?? void 0;
-  return chosen ? resolveHostedTarget(chosen) : null;
+  return (await resolveHostChoiceOrNull(flag, deps))?.target ?? null;
 }
-async function resolveHostSelection(flag, deps) {
-  const target3 = await resolveHostSelectionOrNull(flag, deps);
-  if (!target3) {
+async function resolveHostChoice(flag, deps) {
+  const choice = await resolveHostChoiceOrNull(flag, deps);
+  if (!choice) {
     throw new CliError("USAGE", "no hosted Superbee host selected", {
       help: `pass --host <url> (for example ${String(firstSignInCommand())}) or set ${HOST_ENV}`
     });
   }
-  return target3;
+  return choice;
+}
+async function resolveHostSelection(flag, deps) {
+  return (await resolveHostChoice(flag, deps)).target;
 }
 function directoryForAccount(home2) {
   return (account) => sessionDirFor(home2, account);
@@ -26474,8 +26602,10 @@ function jsonPure(value) {
   if (typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) return Object.values(value).every(jsonPure);
   return false;
 }
-function wholeDocumentRequest(bundleId, intent, okfVersion) {
+function wholeDocumentRequest(bundleId, intent, okfVersion, options = {}) {
   const operation = operationOf(intent);
+  const importing = options.mode === "import";
+  if (importing && operation !== "create") throw new WholeDocumentInputError(`'${intent.target}' is a ${operation}, and only a create may carry imported provenance`, "unsupported_operation");
   if (operation === "delete") return { kind: "delete", operationId: OPERATION_IDS.delete, payload: { bundleId, documentId: intent.target, expectedVersion: intent.base } };
   let parsed2;
   try {
@@ -26484,11 +26614,17 @@ function wholeDocumentRequest(bundleId, intent, okfVersion) {
     throw new WholeDocumentInputError(`'${intent.target}' does not parse: ${error51.message}`);
   }
   const frontmatter = {};
+  const carried = [];
+  const dropped = [];
   for (const [key2, value] of Object.entries(parsed2.frontmatter)) {
     if (!HOSTED_MANAGED_FIELDS.has(key2)) frontmatter[key2] = value;
+    else if (importing && IMPORT_CARRIED_FIELDS.includes(key2)) {
+      frontmatter[key2] = value;
+      carried.push(key2);
+    } else if (importing) dropped.push(key2);
   }
   if (!jsonPure(frontmatter)) throw new WholeDocumentInputError(`'${intent.target}' has frontmatter that is not plain JSON`);
-  const keys = Object.keys(frontmatter);
+  const keys = Object.keys(frontmatter).filter((key2) => !HOSTED_MANAGED_FIELDS.has(key2));
   if (keys.length > FRONTMATTER_KEY_LIMIT) throw new WholeDocumentInputError(`'${intent.target}' has ${keys.length} frontmatter fields; at most ${FRONTMATTER_KEY_LIMIT} are accepted`);
   if (typeof frontmatter.type !== "string" || frontmatter.type.trim() === "") throw new WholeDocumentInputError(`'${intent.target}' has no type`);
   if (keys.some((key2) => UNSAFE_KEYS.has(key2))) throw new WholeDocumentInputError(`'${intent.target}' names a reserved object key in its frontmatter`);
@@ -26497,7 +26633,8 @@ function wholeDocumentRequest(bundleId, intent, okfVersion) {
     kind: "create",
     operationId: OPERATION_IDS.create,
     payload: { bundleId, documentId: intent.target, expectAbsent: true, frontmatter, body: parsed2.body },
-    ...intent.recreates !== void 0 ? { recreates: intent.recreates } : {}
+    ...intent.recreates !== void 0 ? { recreates: intent.recreates } : {},
+    ...importing ? { provenance: { carried, dropped } } : {}
   } : { kind: "replace", operationId: OPERATION_IDS.replace, payload: { ...common, expectedVersion: intent.base } };
 }
 function createWholeDocumentTransport(options) {
@@ -26667,7 +26804,7 @@ function createWholeDocumentTransport(options) {
     }
   };
 }
-var HOSTED_MANAGED_FIELDS, FRONTMATTER_KEY_LIMIT, UNSAFE_KEYS, WHOLE_DOCUMENT_SETTLEMENT, WHOLE_DOCUMENT_BOUNDS, CURRENT_HOST_DOCUMENT_INPUT_BYTES, SYNC_WRITE_ROUTES, OPERATION_IDS, WHOLE_DOCUMENT_INTENT_KINDS, WholeDocumentInputError, UNKNOWN3, encoder2;
+var HOSTED_MANAGED_FIELDS, IMPORT_CARRIED_FIELDS, IMPORT_DROPPED_FIELDS, FRONTMATTER_KEY_LIMIT, UNSAFE_KEYS, WHOLE_DOCUMENT_SETTLEMENT, WHOLE_DOCUMENT_BOUNDS, CURRENT_HOST_DOCUMENT_INPUT_BYTES, SYNC_WRITE_ROUTES, OPERATION_IDS, WHOLE_DOCUMENT_INTENT_KINDS, WholeDocumentInputError, UNKNOWN3, encoder2;
 var init_whole_document_transport = __esm({
   "../core/src/hosted-transport/whole-document-transport.ts"() {
     "use strict";
@@ -26680,6 +26817,8 @@ var init_whole_document_transport = __esm({
     init_version_transport();
     init_read_adapter();
     HOSTED_MANAGED_FIELDS = /* @__PURE__ */ new Set(["actor", "superbee_updated_by", "generated", "verified", "timestamp", "okf_version"]);
+    IMPORT_CARRIED_FIELDS = Object.freeze(["generated", "timestamp", "actor", "okf_version"]);
+    IMPORT_DROPPED_FIELDS = Object.freeze([...HOSTED_MANAGED_FIELDS].filter((field) => !IMPORT_CARRIED_FIELDS.includes(field)));
     FRONTMATTER_KEY_LIMIT = 32;
     UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
     WHOLE_DOCUMENT_SETTLEMENT = "recorded-only";
@@ -129423,11 +129562,13 @@ async function bundleRetire(argv2, partial2 = {}) {
   if (!typed) {
     throw new CliError("USAGE", `'${positionals[0]}' is not a hosted bundle id or <workspace>/<bundle-id>`, { help: `${cliInvocation()} bundle retire --help` });
   }
-  const target3 = await requireHostedBundleHost(values.host, deps.auth.home, deps.auth.env);
+  const named = await requireHostedBundleHost(values.host, deps.auth);
+  const target3 = named.target;
+  const workspace = workspaceForNamedHost(named, values.workspace);
   const host = commandToken(hostArgument(target3));
-  const command = (reference2) => commandFragment`${cliInvocation()} bundle retire ${commandToken(reference2)} --host ${host}${values.workspace !== void 0 ? commandFragment` --workspace ${commandToken(values.workspace)}` : commandFragment``}`;
+  const command = (reference2) => commandFragment`${cliInvocation()} bundle retire ${commandToken(reference2)} --host ${host}${workspace !== void 0 ? commandFragment` --workspace ${commandToken(workspace)}` : commandFragment``}`;
   const resume2 = commandFragment`${command(hostedBundleReferenceText(typed))}${values.json ? commandFragment` --json` : commandFragment``}`;
-  const account = await connectHostedAccount(target3, { ...values.workspace !== void 0 ? { workspace: values.workspace } : {}, resume: resume2 }, { auth: deps.auth, ...deps.fetch ? { fetch: deps.fetch } : {} });
+  const account = await connectHostedAccount(target3, { ...workspace !== void 0 ? { workspace } : {}, resume: resume2 }, { auth: deps.auth, ...deps.fetch ? { fetch: deps.fetch } : {} });
   const resolved = resolveBundleReference(typed, account, target3, command).reference;
   const client = resolved.slug === null ? account.client : account.client.within(resolved.slug);
   const reference = hostedBundleReferenceText(resolved);
@@ -129797,7 +129938,7 @@ async function catalogInner(argv2, deps) {
 }
 async function listHosted(values, deps, home2, stdout) {
   const auth = deps.auth ?? defaultHostedAuthDeps(home2);
-  const target3 = await requireHostedBundleHost(values.host, auth.home, auth.env);
+  const { target: target3 } = await requireHostedBundleHost(values.host, auth);
   const host = hostArgument(target3);
   const resume2 = commandFragment`${cliInvocation()} catalog list --hosted --host ${commandToken(host)}${values.json ? commandFragment` --json` : commandFragment``}`;
   const { client, identity } = await connectHostedAccount(
@@ -131038,9 +131179,9 @@ async function setupHosted(argv2, partial2 = {}) {
     return;
   }
   const mode = resolveMode(values);
-  let target3;
+  let choice;
   try {
-    target3 = await resolveHostSelection(values.url, auth);
+    choice = await resolveHostChoice(values.url, auth);
   } catch (error51) {
     if (error51 instanceof CliError && error51.code === "USAGE" && values.url === void 0) {
       throw new CliError("USAGE", "no hosted Superbee URL: pass --url", { help: `${cliInvocation()} setup hosted --url <hosted-url>` });
@@ -131050,17 +131191,20 @@ async function setupHosted(argv2, partial2 = {}) {
     }
     throw error51;
   }
+  const target3 = choice.target;
+  const requested = workspaceForNamedHost(choice, values.workspace);
   const host = hostArgument(target3);
-  const resume2 = commandFragment`${cliInvocation()} setup hosted --url ${commandToken(host)}${values.workspace !== void 0 ? commandFragment` --workspace ${commandToken(values.workspace)}` : commandFragment``}${values.json ? commandFragment` --json` : commandFragment``}`;
+  const resume2 = commandFragment`${cliInvocation()} setup hosted --url ${commandToken(host)}${requested !== void 0 ? commandFragment` --workspace ${commandToken(requested)}` : commandFragment``}${values.json ? commandFragment` --json` : commandFragment``}`;
   const { identity, workspace: chosen } = await connectHostedAccount(
     target3,
-    { workspace: values.workspace, resume: resume2, otherWorkspace: `${cliInvocation()} setup hosted --url ${commandToken(host)} --workspace <id>` },
+    { workspace: requested, resume: resume2, otherWorkspace: `${cliInvocation()} setup hosted --url ${commandToken(host)} --workspace <id>` },
     { auth, ...partial2.fetch ? { fetch: partial2.fetch } : {} }
   );
   await writeDefaultHost(auth.home, host);
   const workspaces = identity.tenantIds;
   const base = {
     host: target3.origin,
+    ...workspaceOriginView(choice),
     signed_in: true,
     principal: identity.principalId,
     workspaces
@@ -132123,7 +132267,8 @@ async function login(argv2, partial2 = {}) {
   const port = parsePort(values.port);
   const clientIdFlag = values["client-id"] || void 0;
   const auth = { ...deps.auth, env: { ...deps.auth.env, [ACCESS_TOKEN_ENV]: void 0 } };
-  const target3 = await resolveHostSelection(values.host, auth);
+  const choice = await resolveHostChoice(values.host, auth);
+  const target3 = choice.target;
   const signIn = { ...clientIdFlag ? { clientIdFlag } : {} };
   let token;
   if (values.loopback && await readSession(auth.home, target3)) {
@@ -132163,6 +132308,7 @@ ${url2}
         status: token.source === "sign-in" ? "signed_in" : "already_signed_in",
         host: target3.origin,
         audience: target3.audience,
+        ...workspaceOriginView(choice),
         ...session ? sessionView(session) : {},
         ...deps.auth.env[ACCESS_TOKEN_ENV] ? { env_override: `${ACCESS_TOKEN_ENV} is set and takes precedence for hosted commands` } : {},
         help: [`${cliInvocation()} whoami --host ${commandToken(hostArgument(target3))}`]
@@ -132368,8 +132514,11 @@ and it completes sign-in. --wait polls instead, for at most --timeout seconds
 --loopback signs in through a browser redirect to 127.0.0.1 (PKCE), waits at most --timeout
 seconds, then falls back to device sign-in. The link is printed on stderr.
 
-The host is --host, then ${HOST_ENV}, then the host of the last sign-in. The issuer comes from the
-host's protected-resource metadata. The CLI client id comes from --client-id, then
+The host is --host, then ${HOST_ENV}, then the host of the last sign-in. A workspace address
+(<workspace>.<domain>) with no metadata of its own is followed, through its
+/.well-known/superbee-workspace pointer, to the gateway it names under the same domain; the
+session is kept for that gateway (reported as host_from: workspace-origin). The issuer comes from
+the host's protected-resource metadata. The CLI client id comes from --client-id, then
 ${CLIENT_ID_ENV}, then the host's metadata. The refresh token is kept in the OS credential store
 (macOS Keychain, Linux Secret Service); ${CREDENTIAL_STORE_ENV}=file opts in to a 0600 file
 instead. ${ACCESS_TOKEN_ENV} (for CI) is used as given by hosted commands and is never stored.
@@ -132389,10 +132538,12 @@ Options:
 Usage:
   superbee whoami [--host <url>] [--json]
 
-Local and read-only: reports the host, issuer, client, the signed-in subject from the token's
+Read-only: reports the host, issuer, client, the signed-in subject from the token's
 claims (not yet confirmed by the gateway), scopes, token expiry, where the refresh token is kept,
 and any sign-in waiting on the person. Never prints a token. Not signed in is a successful result,
 including on a first run with no host selected yet (it names the sign-in command).
+It reads local state only, except that a host with no stored session that turns out to be a
+workspace's browser address is resolved to its gateway first (its metadata and pointer requests).
 
 Options:
   --host <url>   Hosted Superbee URL (default: ${HOST_ENV}, then the last sign-in)
@@ -133085,18 +133236,18 @@ async function release(folderArg, deps, mode) {
     )
   );
 }
-async function checkoutHost(flag, folder, typed, values, home2, env) {
+async function checkoutHost(flag, folder, typed, values, home2, env, fetchImpl) {
   if (flag === void 0) {
     const real = await realpath11(folder).catch(() => null);
     const bound = real ? await bindingForPath(home2, real).catch(() => null) : null;
-    if (bound) return checkoutTarget(bound);
+    if (bound) return { target: checkoutTarget(bound), workspace: values.workspace, origin: {} };
   }
   const retry = (host) => String(
     commandFragment`${cliInvocation()} checkout ${commandToken(hostedBundleReferenceText(typed))} --host ${commandToken(host)} --dir ${commandToken(folder)}${values.workspace !== void 0 ? commandFragment` --workspace ${commandToken(values.workspace)}` : commandFragment``}${values.json ? commandFragment` --json` : commandFragment``}`
   );
-  const chosen = await hostedWriteHost(flag, home2, retry);
+  const chosen = await hostedWriteHost(flag, home2, retry, fetchImpl);
   if (!chosen) throw notSignedInError(env);
-  return chosen.target;
+  return { target: chosen.target, workspace: workspaceForNamedHost(chosen, values.workspace), origin: workspaceOriginView(chosen) };
 }
 async function checkout(argv2, partial2 = {}) {
   const deps = checkoutDeps(partial2);
@@ -133145,16 +133296,16 @@ async function checkout(argv2, partial2 = {}) {
   const bundleId = typed.bundleId;
   const folder = path53.resolve(deps.cwd, values.dir ?? bundleId);
   assertBundleOutsidePrivateState(folder, deps.auth.home);
-  const target3 = await checkoutHost(values.host, folder, typed, values, deps.auth.home, deps.auth.env);
+  const { target: target3, workspace: workspaceFlag2, origin: hostOrigin } = await checkoutHost(values.host, folder, typed, values, deps.auth.home, deps.auth.env, deps.auth.fetch);
   const prefix = syncRoutePrefix(target3);
-  const resume2 = commandFragment`${cliInvocation()} checkout ${commandToken(hostedBundleReferenceText(typed))} --host ${commandToken(hostArgument(target3))} --dir ${commandToken(folder)}${values.workspace !== void 0 ? commandFragment` --workspace ${commandToken(values.workspace)}` : commandFragment``}${values.json ? commandFragment` --json` : commandFragment``}`;
+  const resume2 = commandFragment`${cliInvocation()} checkout ${commandToken(hostedBundleReferenceText(typed))} --host ${commandToken(hostArgument(target3))} --dir ${commandToken(folder)}${workspaceFlag2 !== void 0 ? commandFragment` --workspace ${commandToken(workspaceFlag2)}` : commandFragment``}${values.json ? commandFragment` --json` : commandFragment``}`;
   const found = await entryKind(folder);
   if (found === "other") {
     throw new CliError("ALREADY_EXISTS", `${folder} exists and is not a folder`, { help: "pass --dir <new folder>" });
   }
   if (found === "dir") {
     const existing = await bindingForPath(deps.auth.home, await realpath11(folder));
-    const sameWorkspace = values.workspace === void 0 || values.workspace === existing?.workspace_slug || values.workspace === existing?.workspace;
+    const sameWorkspace = workspaceFlag2 === void 0 || workspaceFlag2 === existing?.workspace_slug || workspaceFlag2 === existing?.workspace;
     const asked = typed.slug === null && sameWorkspace ? { slug: existing?.workspace_slug ?? null, bundleId } : typed;
     if (existing && bindsBundle(existing, target3, asked)) {
       deps.stdout(render({ checkout: "unchanged", ...bindingView(existing), help: nextSteps(existing.path) }, mode));
@@ -133168,7 +133319,7 @@ async function checkout(argv2, partial2 = {}) {
     });
   }
   await assertStandaloneFolder(folder);
-  const { identity, reader, listed: listed2, workspace, reference, definitionWrites, documentInputBytes } = await connectHostedBundle(typed, target3, values.workspace, deps, resume2);
+  const { identity, reader, listed: listed2, workspace, reference, definitionWrites, documentInputBytes } = await connectHostedBundle(typed, target3, workspaceFlag2, deps, resume2);
   const canonical2 = await canonicalFolder(folder);
   let createdFolder = false;
   const placed = /* @__PURE__ */ new Map();
@@ -133274,6 +133425,7 @@ async function checkout(argv2, partial2 = {}) {
       {
         checkout: "created",
         ...bindingView(result3.binding),
+        ...hostOrigin,
         catalog: cataloged,
         documents: result3.documents,
         root_index: result3.root,
@@ -134170,11 +134322,12 @@ async function exportCommand(argv2, partial2 = {}) {
   }
   let source;
   if (reference) {
+    const named2 = await requireHostedBundleHost(values.host, deps.auth);
     source = {
-      target: await requireHostedBundleHost(values.host, deps.auth.home, deps.auth.env),
+      target: named2.target,
       bundleId: reference.bundleId,
       slug: reference.slug,
-      workspace: values.workspace ?? null,
+      workspace: workspaceForNamedHost(named2, values.workspace) ?? null,
       binding: null
     };
   } else {
@@ -134600,7 +134753,10 @@ function gitVersions(board, id, rel, current, okfVersion, now, documentInputByte
       label: `imported:git/${sha}`,
       author: cleanAuthor(author ?? ""),
       authoredAt: new Date(when).toISOString(),
-      frontmatter: parsed2.frontmatter,
+      // An imported version never asserts verification or host attribution, as a current document does not.
+      frontmatter: Object.fromEntries(
+        Object.entries(parsed2.frontmatter).filter(([key2]) => !IMPORT_DROPPED_FIELDS.includes(key2))
+      ),
       body: parsed2.body ?? ""
     });
   }
@@ -134663,6 +134819,10 @@ async function planPublish(folder, options) {
   const blockers = [];
   const extras = {};
   const documentFiles = [];
+  const provenance2 = {
+    carried: Object.fromEntries(IMPORT_CARRIED_FIELDS.map((field) => [field, 0])),
+    dropped: Object.fromEntries(IMPORT_DROPPED_FIELDS.map((field) => [field, 0]))
+  };
   const entries = await walkAll(folder);
   let rootIndex = null;
   try {
@@ -134734,7 +134894,7 @@ async function planPublish(folder, options) {
     }
     let request3;
     try {
-      request3 = wholeDocumentRequest("publish", { kind: "document.write", target: id, base: null, content: utf83(bytes) }, okfVersion);
+      request3 = wholeDocumentRequest("publish", { kind: "document.write", target: id, base: null, content: utf83(bytes) }, okfVersion, { mode: "import" });
     } catch (error51) {
       if (error51 instanceof WholeDocumentInputError) {
         blockers.push({ path: entry.rel, reason: "not_sendable", message: error51.message });
@@ -134742,7 +134902,13 @@ async function planPublish(folder, options) {
       }
       throw error51;
     }
-    if (request3.kind === "delete") throw new Error(`'${id}' became a delete request`);
+    if (request3.kind !== "create") throw new Error(`'${id}' became a ${request3.kind} request`);
+    if (Buffer.byteLength(JSON.stringify(request3.payload.frontmatter)) > FRONTMATTER_JSON_BYTES) {
+      blockers.push({ path: entry.rel, reason: "too_large", message: `'${id}' has more than the ${FRONTMATTER_JSON_BYTES / 1024} KiB of frontmatter the host stores, counting ${request3.provenance.carried.join(", ")}` });
+      continue;
+    }
+    for (const field of request3.provenance.carried) provenance2.carried[field] = (provenance2.carried[field] ?? 0) + 1;
+    for (const field of request3.provenance.dropped) provenance2.dropped[field] = (provenance2.dropped[field] ?? 0) + 1;
     documents.push({ id, frontmatter: request3.payload.frontmatter, body: request3.payload.body ?? "" });
     documentFiles.push({ id, rel: entry.rel, text: utf83(bytes) });
   }
@@ -134789,7 +134955,7 @@ async function planPublish(folder, options) {
   const draft = { documents, reserved, blobs: blobs2, history };
   const sendPath = publishPath(draft);
   if (sendPath.mode === "staged") blockers.push(...stagedBlockers(draft));
-  return { documents, reserved, blobs: blobs2, history, path: sendPath, skipped, blockers, historyPlan, extras };
+  return { documents, reserved, blobs: blobs2, history, path: sendPath, skipped, blockers, historyPlan, extras, provenance: provenance2 };
 }
 function publishPath(plan) {
   const bounds = PUBLISH_BOUNDS;
@@ -135329,7 +135495,15 @@ function summary(plan) {
     reserved_files: plan.reserved.length,
     other_files: plan.blobs.length,
     sent: plan.path.mode === "one-shot" ? "one request" : `staged: ${plan.path.why}; a list of everything, parts of about 1 MiB, each file, then commits until created (resumable)`,
-    history: { mode: plan.historyPlan.mode, versions: plan.historyPlan.versions, ...plan.historyPlan.skipped > 0 ? { skipped: plan.historyPlan.skipped } : {}, note: plan.historyPlan.note }
+    history: { mode: plan.historyPlan.mode, versions: plan.historyPlan.versions, ...plan.historyPlan.skipped > 0 ? { skipped: plan.historyPlan.skipped } : {}, note: plan.historyPlan.note },
+    provenance: provenanceOf(plan)
+  };
+}
+function provenanceOf(plan) {
+  return {
+    carried: plan.provenance.carried,
+    dropped: plan.provenance.dropped,
+    note: "provenance travels as each file states it (a claim, not a verification); verification events and the last-editor attribution stay in the folder, and the host attributes the creation to you"
   };
 }
 function createRefusal(code3, message, context) {
@@ -135521,15 +135695,17 @@ async function publish(argv2, partial2 = {}) {
     });
   }
   const withHistory = values["with-history"] === true;
-  const yesCommandFor = (host) => commandFragment`${cliInvocation()} publish --to hosted${values.dir !== void 0 ? commandFragment` --dir ${commandToken(canonical2)}` : commandFragment``}${host !== null ? commandFragment` --host ${commandToken(host)}` : commandFragment``}${values.workspace !== void 0 ? commandFragment` --workspace ${commandToken(values.workspace)}` : commandFragment``} --bundle-id ${commandToken(bundleId)}${values.name !== void 0 ? commandFragment` --name ${commandToken(name)}` : commandFragment``}${withHistory ? commandFragment` --with-history` : commandFragment``} --yes${values.json ? commandFragment` --json` : commandFragment``}`;
+  let workspaceFlag2 = values.workspace;
+  const yesCommandFor = (host) => commandFragment`${cliInvocation()} publish --to hosted${values.dir !== void 0 ? commandFragment` --dir ${commandToken(canonical2)}` : commandFragment``}${host !== null ? commandFragment` --host ${commandToken(host)}` : commandFragment``}${workspaceFlag2 !== void 0 ? commandFragment` --workspace ${commandToken(workspaceFlag2)}` : commandFragment``} --bundle-id ${commandToken(bundleId)}${values.name !== void 0 ? commandFragment` --name ${commandToken(name)}` : commandFragment``}${withHistory ? commandFragment` --with-history` : commandFragment``} --yes${values.json ? commandFragment` --json` : commandFragment``}`;
   let chosen = null;
   let ambiguous = null;
   try {
-    chosen = await hostedWriteHost(values.host, home2, (host) => String(yesCommandFor(host)));
+    chosen = await hostedWriteHost(values.host, home2, (host) => String(yesCommandFor(host)), values.yes ? deps.auth.fetch : null);
   } catch (error51) {
     if (values.yes || !(error51 instanceof CliError) || error51.details?.reason !== "ambiguous_host") throw error51;
     ambiguous = error51;
   }
+  if (chosen) workspaceFlag2 = workspaceForNamedHost(chosen, values.workspace);
   const target3 = chosen?.target ?? null;
   const planFor = (documentInputBytes) => planPublish(canonical2, withHistory ? { history: true, ...board ? { board } : {}, now: deps.auth.now(), documentInputBytes } : { history: false, documentInputBytes });
   let plan = await planFor(CURRENT_HOST_DOCUMENT_INPUT_BYTES);
@@ -135600,7 +135776,7 @@ async function publish(argv2, partial2 = {}) {
   const otherWorkspace = `${cliInvocation()} publish --to hosted --host ${commandToken(bindingHostArgument(target3))} --workspace <id> --bundle-id ${commandToken(bundleId)} --yes`;
   const { client, identity, workspace } = await connectHostedAccount(
     target3,
-    { workspace: values.workspace, resume: yesCommand, otherWorkspace, deadlineMs: CREATE_DEADLINE_MS },
+    { workspace: workspaceFlag2, resume: yesCommand, otherWorkspace, deadlineMs: CREATE_DEADLINE_MS },
     { auth: deps.auth, ...deps.fetch ? { fetch: deps.fetch } : {} }
   );
   if (workspace === null) {
@@ -135636,7 +135812,8 @@ async function publish(argv2, partial2 = {}) {
             documents: created.documents ?? plan.documents.length,
             reserved_files: created.reserved ?? plan.reserved.length,
             other_files: created.blobs ?? plan.blobs.length,
-            history: created.history ?? { imported: plan.history.length, verified: false }
+            history: created.history ?? { imported: plan.history.length, verified: false },
+            provenance: { carried: plan.provenance.carried, dropped: plan.provenance.dropped }
           },
           folder: canonical2,
           home: facts.home,
@@ -135730,7 +135907,8 @@ async function publish(argv2, partial2 = {}) {
           documents: created.documents ?? plan.documents.length,
           reserved_files: created.reserved ?? plan.reserved.length,
           other_files: created.blobs ?? plan.blobs.length,
-          history: created.history ?? { imported: plan.history.length, verified: false }
+          history: created.history ?? { imported: plan.history.length, verified: false },
+          provenance: { carried: plan.provenance.carried, dropped: plan.provenance.dropped }
         },
         folder: canonical2,
         home: "hosted",
@@ -135799,6 +135977,10 @@ Without --yes, previews only, with no network: what travels (documents, reserved
 files), what stays (dot-files, links), how it is sent, every bound the host enforces, the history
 plan, and what will happen to the folder.
 
+Each document's provenance (generated, timestamp, actor, okf_version) travels as its file states
+it, a claim rather than a verification; verified and superbee_updated_by never travel. The
+preview and the receipt count both, per field.
+
 A bundle within one request's bounds (at most 1,000 documents, 100 other files of 1 MB each,
 1,000 earlier versions, 1,500 objects in all, 3 MiB) is sent in one request. A larger one is sent
 staged: a list of everything, then parts of about 1 MiB, then each file, then commits until the
@@ -135909,10 +136091,12 @@ async function accessList(argv2, deps) {
     return;
   }
   const typed = typedReference(positionals[0]);
-  const target3 = await requireHostedBundleHost(values.host, deps.auth.home, deps.auth.env);
+  const named = await requireHostedBundleHost(values.host, deps.auth);
+  const target3 = named.target;
+  const workspace = workspaceForNamedHost(named, values.workspace);
   const command = (reference) => commandFragment`${cliInvocation()} access list ${commandToken(reference)}${hostFlag(target3)}`;
-  const resume2 = commandFragment`${command(hostedBundleReferenceText(typed))}${workspaceFlag(values.workspace)}${values.json ? commandFragment` --json` : commandFragment``}`;
-  const reached = await reach(typed, target3, values.workspace, resume2, deps, command);
+  const resume2 = commandFragment`${command(hostedBundleReferenceText(typed))}${workspaceFlag(workspace)}${values.json ? commandFragment` --json` : commandFragment``}`;
+  const reached = await reach(typed, target3, workspace, resume2, deps, command);
   const answer2 = await postRoute({ client: reached.client, resume: resume2, reference: reached.reference }, "access-list", { bundleId: reached.bundleId });
   if (!answer2.ok) throw accessRefusal(answer2.code, answer2.message, { reference: reached.reference, host: target3, again: resume2 });
   const data = answer2.data;
@@ -135985,8 +136169,10 @@ async function accessChange(action, argv2, deps) {
     throw usage2(wanted === void 0 ? "grant needs --level read or --level write" : `'${wanted}' is not a level: read or write`);
   }
   const mode = resolveMode(values);
-  const target3 = await requireHostedBundleHost(values.host, deps.auth.home, deps.auth.env);
-  const command = (reference) => commandFragment`${cliInvocation()} access ${commandToken(action)} ${commandToken(reference)} ${commandToken(person)}${action === "grant" ? commandFragment` --level ${commandToken(wanted)}` : commandFragment``}${hostFlag(target3)}${workspaceFlag(values.workspace)} --yes`;
+  const named = await requireHostedBundleHost(values.host, { ...deps.auth, fetch: values.yes ? deps.auth.fetch : null });
+  const target3 = named.target;
+  const workspace = workspaceForNamedHost(named, values.workspace);
+  const command = (reference) => commandFragment`${cliInvocation()} access ${commandToken(action)} ${commandToken(reference)} ${commandToken(person)}${action === "grant" ? commandFragment` --level ${commandToken(wanted)}` : commandFragment``}${hostFlag(target3)}${workspaceFlag(workspace)} --yes`;
   const typedText = hostedBundleReferenceText(typed);
   const yesCommand = commandFragment`${command(typedText)}${values.json ? commandFragment` --json` : commandFragment``}`;
   if (!values.yes) {
@@ -135999,7 +136185,7 @@ async function accessChange(action, argv2, deps) {
           person,
           ...action === "grant" ? { level: wanted } : {},
           host: target3.origin,
-          ...values.workspace !== void 0 ? { workspace: values.workspace } : {},
+          ...workspace !== void 0 ? { workspace } : {},
           will: action === "grant" ? `give ${person} ${wanted} access to '${typedText}' (or change their level to ${wanted}); they must already be a member of the workspace (invite them from the Members page in the Superbee app first)` : `take ${person}'s access to '${typedText}' away; they stay a member of the workspace`,
           needs: "a workspace admin, granting no more than your own level on the bundle",
           network: "none (preview)",
@@ -136010,7 +136196,7 @@ async function accessChange(action, argv2, deps) {
     );
     return;
   }
-  const reached = await reach(typed, target3, values.workspace, yesCommand, deps, (reference) => command(reference));
+  const reached = await reach(typed, target3, workspace, yesCommand, deps, (reference) => command(reference));
   const route = action === "grant" ? "access-grant" : "access-revoke";
   const home2 = deps.auth.home;
   const requestId2 = await accessRequestId(home2, target3.origin, reached.reference, person, action === "grant" ? `grant:${wanted}` : "revoke", deps.auth.now());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.3-pre.2",
+  "version": "0.4.3-pre.3",
   "type": "module",
   "description": "Agent-facing Superbee CLI for reading and writing local OKF knowledge bundles: context notes, docs, cross-links, and live bundle Views.",
   "keywords": [