@stigmer/server 3.15.3-dev.20260914121148 → 3.15.3-dev.20260916211208

package/src/pipeline/steps/helpers.ts

@@ -109,7 +109,10 @@ export function requireOrgForReference(
     scopeType = meta.authorization?.scopeType;
     kindName = meta.name;
   } catch (error) {
-    throw internalError(error, "failed to resolve kind metadata for reference org check");
+    throw internalError(
+      error,
+      "failed to resolve kind metadata for reference org check",
+    );
   }
   // protobuf-es strips the shared enum prefix: proto
   // AUTHORIZATION_SCOPE_TYPE_ORGANIZATION generates as ORGANIZATION.

package/src/pipeline/steps/index-search.ts

@@ -37,26 +37,34 @@ export function newIndexSearchStep<Desc extends DescMessage>(
       const resource = ctx.newState;
       const metadata = metadataOf(resource);
       if (metadata === undefined || metadata.id === "") {
-        logger.warn("IndexSearch: resource has no metadata or ID, skipping indexing");
+        logger.warn(
+          "IndexSearch: resource has no metadata or ID, skipping indexing",
+        );
         return;
       }
 
       const entry = extractor.getSearchIndexEntry(resource);
       if (entry === undefined) {
-        logger.warn("IndexSearch: extractor returned no entry, skipping indexing", {
-          id: metadata.id,
-        });
+        logger.warn(
+          "IndexSearch: extractor returned no entry, skipping indexing",
+          {
+            id: metadata.id,
+          },
+        );
         return;
       }
 
       try {
         await store.upsertSearchIndex(ctx.apiResourceKind, metadata.id, entry);
       } catch (error) {
-        logger.warn("IndexSearch: failed to update search index (best-effort)", {
-          id: metadata.id,
-          kind: apiResourceKindName(ctx.apiResourceKind),
-          error: error instanceof Error ? error.message : String(error),
-        });
+        logger.warn(
+          "IndexSearch: failed to update search index (best-effort)",
+          {
+            id: metadata.id,
+            kind: apiResourceKindName(ctx.apiResourceKind),
+            error: error instanceof Error ? error.message : String(error),
+          },
+        );
       }
     },
   };
@@ -72,18 +80,23 @@ export function newDeleteSearchIndexStep<Desc extends DescMessage>(
       const id = ctx.get(RESOURCE_ID_KEY);
       if (typeof id !== "string" || id === "") {
         throw internalError(
-          new Error("resource id not found in context (ExtractResourceId must run first)"),
+          new Error(
+            "resource id not found in context (ExtractResourceId must run first)",
+          ),
           "delete search index ordering",
         );
       }
       try {
         await store.deleteSearchIndex(ctx.apiResourceKind, id);
       } catch (error) {
-        logger.warn("DeleteSearchIndex: failed to remove search index entry (best-effort)", {
-          id,
-          kind: apiResourceKindName(ctx.apiResourceKind),
-          error: error instanceof Error ? error.message : String(error),
-        });
+        logger.warn(
+          "DeleteSearchIndex: failed to remove search index entry (best-effort)",
+          {
+            id,
+            kind: apiResourceKindName(ctx.apiResourceKind),
+            error: error instanceof Error ? error.message : String(error),
+          },
+        );
       }
     },
   };

package/src/pipeline/steps/load-existing.ts

@@ -15,7 +15,11 @@ import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { getKindName } from "../apiresource-meta.js";
-import { internalError, invalidArgumentError, notFoundError } from "../errors.js";
+import {
+  internalError,
+  invalidArgumentError,
+  notFoundError,
+} from "../errors.js";
 import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
 import { findResourceBySlug } from "./helpers.js";
@@ -32,7 +36,10 @@ export function newLoadExistingStep<Desc extends DescMessage>(
     async execute(ctx: RequestContext<Desc>): Promise<void> {
       const metadata = metadataOf(ctx.newState);
       if (metadata === undefined) {
-        throw internalError(new Error("resource metadata is nil"), "load existing");
+        throw internalError(
+          new Error("resource metadata is nil"),
+          "load existing",
+        );
       }
 
       let existing: MessageShape<Desc>;
@@ -64,7 +71,9 @@ export function newLoadExistingStep<Desc extends DescMessage>(
         // Populate the id so merge and persist have it.
         metadata.id = metadataOf(existing)?.id ?? "";
       } else {
-        throw invalidArgumentError("resource id or slug is required for update");
+        throw invalidArgumentError(
+          "resource id or slug is required for update",
+        );
       }
 
       ctx.set(EXISTING_RESOURCE_KEY, existing);

package/src/pipeline/steps/references.ts

@@ -31,13 +31,18 @@ import { messageFieldByName, metadataOf } from "./shapes.js";
 const API_RESOURCE_REFERENCE_TYPE =
   "ai.stigmer.commons.apiresource.ApiResourceReference";
 
-export function newNormalizeReferencesStep<Desc extends DescMessage>(): PipelineStep<Desc> {
+export function newNormalizeReferencesStep<
+  Desc extends DescMessage,
+>(): PipelineStep<Desc> {
   return {
     name: "NormalizeReferences",
     execute(ctx: RequestContext<Desc>): void {
       const metadata = metadataOf(ctx.newState);
       if (metadata === undefined) {
-        throw internalError(new Error("resource metadata is nil"), "normalize references");
+        throw internalError(
+          new Error("resource metadata is nil"),
+          "normalize references",
+        );
       }
       // No org to resolve from — skip silently; required-org validation is
       // the validation step's responsibility, not this one's.
@@ -100,6 +105,35 @@ export function newValidateReferencesStep<Desc extends DescMessage>(
   };
 }
 
+/** One reference a spec carries, as the walker reads it. */
+export interface SpecReference {
+  readonly kind: ApiResourceKind;
+  readonly slug: string;
+  readonly org: string;
+}
+
+/**
+ * Every ApiResourceReference in a resource's spec — the same walk
+ * ValidateReferences runs, exported for the readers that ask the reverse
+ * question ("who references this?"): the plugin delete guard scans an
+ * organization's agents and workflows for references to a member it is
+ * about to remove.
+ */
+export function collectSpecReferences(
+  schema: DescMessage,
+  msg: Parameters<typeof reflect>[1],
+): SpecReference[] {
+  const refs: SpecReference[] = [];
+  forEachSpecReference(schema, msg, (ref) => {
+    refs.push({
+      kind: numberField(ref, "kind") as ApiResourceKind,
+      slug: stringField(ref, "slug"),
+      org: stringField(ref, "org"),
+    });
+  });
+  return refs;
+}
+
 /**
  * Walks the resource's spec and invokes fn on every ApiResourceReference
  * (singular, repeated, and map-valued message fields, recursively) —

package/src/pipeline/steps/resolve-artifact-source.ts

@@ -0,0 +1,66 @@
+/**
+ * ResolveArtifactSource — materialises the archive bytes of a push-shaped
+ * request from whichever source it carries: inline bytes pass through; an
+ * upload reference is consumed HERE, which retires the single-use
+ * reference whatever happens downstream. Proto validation has already
+ * guaranteed exactly one source. Downstream steps read the bytes from the
+ * context key and never touch the request's fields, so the two sources
+ * are indistinguishable past this point.
+ *
+ * Skills carried this step alone (the Go ResolveArtifactSource port);
+ * plugins are pushed the same two ways over the same upload slots (one
+ * upload surface, as boot/compose.ts wires it), so the step lives
+ * here and each kind names its lane-absent sentence and the request
+ * fields it reads.
+ *
+ * The unusable-reference arm is INVALID_ARGUMENT, not a server fault: an
+ * unknown, expired, already consumed, or minted-but-never-uploaded
+ * reference all mean the client must re-mint and re-upload.
+ */
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+
+import type { UploadSlots } from "../../domain/skill/transfer/slots.js";
+import { failedPreconditionError, invalidArgumentError } from "../errors.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+
+/** Where the resolved bytes ride for every downstream step. */
+export const ARTIFACT_BYTES_KEY = "pushArtifactBytes";
+
+export interface ArtifactSourceBinding<Desc extends DescMessage> {
+  /** The request's two sources; exactly one is set by proto validation. */
+  source(input: MessageShape<Desc>): {
+    readonly artifact: Uint8Array;
+    readonly artifactUploadRef: string;
+  };
+  /** The FailedPrecondition copy when no lane is configured; each kind pins its own. */
+  readonly laneNotConfigured: string;
+}
+
+export function newResolveArtifactSourceStep<Desc extends DescMessage>(
+  slots: UploadSlots | undefined,
+  binding: ArtifactSourceBinding<Desc>,
+): PipelineStep<Desc> {
+  return {
+    name: "ResolveArtifactSource",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const { artifact, artifactUploadRef } = binding.source(ctx.input);
+      if (artifactUploadRef === "") {
+        ctx.set(ARTIFACT_BYTES_KEY, artifact);
+        return;
+      }
+      if (slots === undefined) {
+        throw failedPreconditionError(binding.laneNotConfigured);
+      }
+      let data: Uint8Array;
+      try {
+        data = await slots.consume(artifactUploadRef);
+      } catch (error) {
+        throw invalidArgumentError(
+          `artifact_upload_ref not usable: ${error instanceof Error ? error.message : String(error)} — request a new upload URL via createArtifactUploadUrl`,
+        );
+      }
+      ctx.set(ARTIFACT_BYTES_KEY, data);
+    },
+  };
+}

package/src/pipeline/steps/server-stamped-reserved-labels.ts

@@ -36,7 +36,8 @@ export function recordServerStampedReservedLabels<Desc extends DescMessage>(
   ...keys: ReadonlyArray<string>
 ): void {
   const existing = ctx.get(STAMPED_KEYS_CONTEXT_KEY);
-  const stamped = existing instanceof Set ? (existing as Set<string>) : new Set<string>();
+  const stamped =
+    existing instanceof Set ? (existing as Set<string>) : new Set<string>();
   for (const key of keys) {
     stamped.add(key);
   }

package/src/pipeline/steps/slug.ts

@@ -14,14 +14,19 @@ import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
 import { metadataOf } from "./shapes.js";
 
-export function newResolveSlugStep<Desc extends DescMessage>(): PipelineStep<Desc> {
+export function newResolveSlugStep<
+  Desc extends DescMessage,
+>(): PipelineStep<Desc> {
   return {
     name: "ResolveSlug",
     execute(ctx: RequestContext<Desc>): void {
       const metadata = metadataOf(ctx.newState);
       if (metadata === undefined) {
         // A server-side programming error, not bad client input (Go).
-        throw internalError(new Error("resource metadata is nil"), "slug resolution");
+        throw internalError(
+          new Error("resource metadata is nil"),
+          "slug resolution",
+        );
       }
       if (metadata.slug !== "") {
         return; // already set — idempotent

package/src/pipeline/steps/validate-visibility.ts

@@ -34,7 +34,9 @@ import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
 import { metadataOf } from "./shapes.js";
 
-export function newValidateVisibilityStep<Desc extends DescMessage>(): PipelineStep<Desc> {
+export function newValidateVisibilityStep<
+  Desc extends DescMessage,
+>(): PipelineStep<Desc> {
   return {
     name: "ValidateVisibility",
     execute(ctx: RequestContext<Desc>): void {
@@ -72,7 +74,12 @@ export function rejectDefaultInstanceVisibilityUpdate(): never {
 }
 
 /** Go rejectUnsupportedVisibility (the shared level check + copy). */
-function rejectUnsupportedVisibility(
+/**
+ * The one sentence for a level a kind does not support. Exported for the
+ * push-shaped chains whose requested level rides the request rather than
+ * a resource's metadata (plugin push), so the copy stays in one place.
+ */
+export function rejectUnsupportedVisibility(
   kind: ApiResourceKind,
   visibility: ApiResourceVisibility,
 ): void {

package/src/pipeline/steps/validation.ts

@@ -23,7 +23,9 @@ export function validator(): Validator {
   return sharedValidator;
 }
 
-export function newValidateProtoStep<Desc extends DescMessage>(): PipelineStep<Desc> {
+export function newValidateProtoStep<
+  Desc extends DescMessage,
+>(): PipelineStep<Desc> {
   return {
     name: "ValidateProto",
     execute(ctx: RequestContext<Desc>): void {

package/src/pipeline/steps/version-archive.ts

@@ -0,0 +1,225 @@
+/**
+ * The write side of content-addressed versioning, shared by every kind
+ * whose version is the SHA-256 of a pushed archive (skills, plugins): the
+ * "archive the head" step a push runs after the head is fully populated,
+ * and the best-effort archive cleanup a delete runs before the row. Skills
+ * carried both alone (#341, adopted for skills in #475; the Go
+ * ArchiveCurrentSkillStep / DeleteSkillArchivesStep port); plugins need the
+ * identical semantics over another schema, so the steps live here and each
+ * kind names its step (`ArchiveCurrentSkill`, `ArchiveCurrentPlugin`), its
+ * context key and where its hash and tag live.
+ *
+ * The load-bearing semantics, all preserved from the skill port:
+ *   - repoint-never-duplicate: re-pushing EVER-archived content repoints the
+ *     head to the existing audit row (an A→B→A re-push must not duplicate
+ *     A's row);
+ *   - snapshots archive TAGLESS; the audit tag COLUMN is the tag's only
+ *     home, assigned through the single-holder setAuditTag primitive —
+ *     assigned even when the content was already archived, because
+ *     re-pushing under a new tag is the only retag path;
+ *   - safe degradation: archive failure clears the version hash from the
+ *     head (the persisted head never references an unresolvable audit
+ *     entry); tag-assignment failure clears the live tag.
+ *
+ * Proven by the skill domain's __tests__/push-degradation.test.ts (the
+ * failing-store arms) and both kinds' conformance suites (the
+ * content-addressed versioning blocks).
+ */
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+
+import type { Logger } from "../../boot/logger.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { AuditNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+import { RESOURCE_ID_KEY } from "./delete.js";
+import { metadataOf } from "./shapes.js";
+
+/** What a content-versioned kind must expose for its head to be archived. */
+export interface ArchiveCurrentVersionBinding<Desc extends DescMessage> {
+  /** The step's name in the chain; shared vocabulary, never renamed. */
+  readonly stepName: string;
+  /** The context key the fully populated head rides. */
+  readonly resourceKey: string;
+  readonly schema: Desc;
+  /** The noun in log lines: "skill", "plugin". */
+  readonly noun: string;
+  headHashOf(resource: MessageShape<Desc>): string;
+  /** Degradation arm: the head must never reference an unresolvable audit row. */
+  clearHeadHash(resource: MessageShape<Desc>): void;
+  liveTagOf(resource: MessageShape<Desc>): string;
+  /** Degradation arm: the live tag must agree with the audit column. */
+  clearLiveTag(resource: MessageShape<Desc>): void;
+}
+
+/**
+ * Repoint or archive, then the single-holder tag assignment, each with its
+ * safe degradation. Runs AFTER the populate step so the archived snapshot
+ * is the fully populated head.
+ */
+export function newArchiveCurrentVersionStep<
+  Desc extends DescMessage,
+  RequestDesc extends DescMessage,
+>(
+  store: Store,
+  logger: Logger,
+  binding: ArchiveCurrentVersionBinding<Desc>,
+): PipelineStep<RequestDesc> {
+  return {
+    name: binding.stepName,
+    async execute(ctx: RequestContext<RequestDesc>): Promise<void> {
+      const resource = ctx.get(binding.resourceKey) as MessageShape<Desc>;
+      const versionHash = binding.headHashOf(resource);
+      if (versionHash === "") {
+        return;
+      }
+      const tag = binding.liveTagOf(resource);
+      const resourceId = metadataOf(resource)?.id ?? "";
+      const idField = `${binding.noun}Id`;
+
+      // Repoint, never duplicate: if this content was ever archived, the
+      // head simply repoints to the existing row and only the tag
+      // assignment below still runs. An unexpected lookup failure degrades
+      // to archiving anyway — a possible duplicate row beats a failed push
+      // (readers resolve duplicates newest-wins).
+      let alreadyArchived = false;
+      try {
+        await store.getAuditByHash(
+          ctx.apiResourceKind,
+          resourceId,
+          versionHash,
+          binding.schema,
+        );
+        alreadyArchived = true;
+      } catch (error) {
+        if (!(error instanceof AuditNotFoundError)) {
+          logger.warn(
+            `Could not check for an existing archived ${binding.noun} version — archiving anyway`,
+            {
+              [idField]: resourceId,
+              versionHash,
+              error: error instanceof Error ? error.message : String(error),
+            },
+          );
+        }
+      }
+
+      if (!alreadyArchived) {
+        // Archive the snapshot tagless: the tag lives only in the audit tag
+        // column (the source of truth), assigned below through the
+        // single-holder primitive — a later tag move never rewrites this
+        // immutable content.
+        try {
+          await store.saveAudit(
+            ctx.apiResourceKind,
+            resourceId,
+            binding.schema,
+            resource,
+            versionHash,
+            "",
+          );
+        } catch (error) {
+          logger.error(
+            `Failed to archive ${binding.noun} version — reverting the version hash to maintain the audit-resolvability invariant`,
+            {
+              [idField]: resourceId,
+              versionHash,
+              error: error instanceof Error ? error.message : String(error),
+            },
+          );
+          // Revert: the persisted head must never reference an audit entry
+          // that does not exist. The push still succeeds, but without
+          // version tracking for this apply.
+          binding.clearHeadHash(resource);
+          return;
+        }
+      }
+
+      // Assign the requested tag through setAuditTag — the single-holder
+      // primitive — so the head version (freshly archived or repointed-to)
+      // becomes the tag's sole holder; any prior holder is cleared.
+      if (tag !== "") {
+        try {
+          await store.setAuditTag(
+            ctx.apiResourceKind,
+            resourceId,
+            versionHash,
+            tag,
+          );
+        } catch (error) {
+          logger.error(
+            `Archived ${binding.noun} version but failed to assign its tag — clearing the live tag to stay consistent with the audit column`,
+            {
+              [idField]: resourceId,
+              versionHash,
+              tag,
+              error: error instanceof Error ? error.message : String(error),
+            },
+          );
+          // The audit head is now untagged; keep the live head consistent
+          // so get / getByReference never advertise a tag the store cannot
+          // resolve.
+          binding.clearLiveTag(resource);
+        }
+      }
+
+      if (alreadyArchived) {
+        logger.info(
+          `${capitalize(binding.noun)} version content already archived — repointed head without a new history row`,
+          { [idField]: resourceId, versionHash, tag },
+        );
+      } else {
+        logger.info(`Archived ${binding.noun} version to audit history`, {
+          [idField]: resourceId,
+          versionHash,
+          tag,
+        });
+      }
+    },
+  };
+}
+
+/**
+ * Best-effort audit cleanup BEFORE the resource row (no FK cascade in the
+ * schema, by design): failures log and never block the delete. Reads the
+ * id ExtractResourceId set.
+ */
+export function newDeleteVersionArchivesStep<RequestDesc extends DescMessage>(
+  store: Store,
+  logger: Logger,
+  binding: { readonly stepName: string; readonly noun: string },
+): PipelineStep<RequestDesc> {
+  return {
+    name: binding.stepName,
+    async execute(ctx: RequestContext<RequestDesc>): Promise<void> {
+      const resourceId = ctx.get(RESOURCE_ID_KEY);
+      if (typeof resourceId !== "string") {
+        throw new Error(
+          "resource id not found in context (ExtractResourceIdStep must run first)",
+        );
+      }
+      const idField = `${binding.noun}Id`;
+      try {
+        const deletedCount = await store.deleteAuditByResourceId(
+          ctx.apiResourceKind,
+          resourceId,
+        );
+        if (deletedCount > 0) {
+          logger.info(`Deleted archive records for ${binding.noun}`, {
+            [idField]: resourceId,
+            count: deletedCount,
+          });
+        }
+      } catch (error) {
+        logger.warn(`failed to delete ${binding.noun} archives (best-effort)`, {
+          [idField]: resourceId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    },
+  };
+}
+
+function capitalize(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}