@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/domain/plugin/search-extractor.ts

@@ -0,0 +1,60 @@
+/**
+ * Plugin search extractor — both sides of the searchable contract (the
+ * index side pipeline/steps/index-search.ts consumes, the query side the
+ * SearchService renders). A plugin's summary is its manifest description;
+ * its keywords join the tags so `stigmer list plugin` and the console's
+ * search find a plugin by what its author called it.
+ */
+import type { Message } from "@bufbuild/protobuf";
+
+import { PluginSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/api_pb";
+import type { Plugin } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+import { buildSearchResult } from "../../query/search/extractor.js";
+import type { SearchableExtractor } from "../../query/search/extractor.js";
+import type { SearchIndexEntry } from "../../store/interface.js";
+
+export const pluginSearchExtractor: SearchableExtractor = {
+  kind: ApiResourceKind.plugin,
+  schema: PluginSchema,
+
+  getSearchSummary(resource: Message): string {
+    const plugin = resource as unknown as Plugin;
+    return plugin.spec?.description ?? "";
+  },
+
+  toSearchResult(resource: Message, score: number): SearchResult | undefined {
+    const plugin = resource as unknown as Plugin;
+    return buildSearchResult({
+      kind: ApiResourceKind.plugin,
+      metadata: plugin.metadata,
+      summary: plugin.spec?.description ?? "",
+      score,
+      createdAt: plugin.status?.audit?.specAudit?.createdAt,
+      updatedAt: plugin.status?.audit?.specAudit?.updatedAt,
+    });
+  },
+
+  getSearchIndexEntry(resource: Message): SearchIndexEntry | undefined {
+    const plugin = resource as unknown as Plugin;
+    const metadata = plugin.metadata;
+    if (metadata === undefined) {
+      return undefined;
+    }
+    return {
+      name: metadata.name,
+      description: plugin.spec?.description ?? "",
+      // The index carries one tags string; the manifest's keywords are
+      // what an author expects a search to match, so they join the tags.
+      tags: [...metadata.tags, ...(plugin.spec?.keywords ?? [])].join(" "),
+      org: metadata.org,
+      visibility: ApiResourceVisibility[metadata.visibility] ?? "",
+      createdAt: Number(
+        plugin.status?.audit?.specAudit?.createdAt?.seconds ?? 0n,
+      ),
+    };
+  },
+};

package/src/domain/skill/constants.ts

@@ -8,21 +8,18 @@
  */
 
 /**
- * The compressed-artifact ceiling. Exported because it is the platform's
- * skill size limit, not just an extraction guard: the transfer lane
- * (createArtifactUploadUrl) enforces it before any bytes move, and clients
- * quote it in fail-loud size errors (#675). Go: storage.MaxZipSize.
+ * The archive budgets (compressed ceiling, uncompressed total, ratio, file
+ * count) are the platform's, shared with every archive-shaped push since
+ * plugins arrived; they live in src/archive/limits.ts and are re-exported
+ * here so the skill domain's consumers keep their names. Go:
+ * storage.MaxZipSize and its three siblings.
  */
-export const MAX_ZIP_SIZE = 100 * 1024 * 1024;
-
-/** Total declared-uncompressed budget across all entries (ZIP-bomb guard). */
-export const MAX_UNCOMPRESSED_SIZE = 500 * 1024 * 1024;
-
-/** Per-file declared compression ratio ceiling (ZIP-bomb guard). */
-export const MAX_COMPRESSION_RATIO = 100;
-
-/** Entry-count ceiling. */
-export const MAX_FILES = 10_000;
+export {
+  MAX_COMPRESSION_RATIO,
+  MAX_FILES,
+  MAX_UNCOMPRESSED_SIZE,
+  MAX_ZIP_SIZE,
+} from "../../archive/limits.js";
 
 /** SKILL.md in-memory extraction cap (memory-exhaustion guard). */
 export const MAX_SKILL_MD_SIZE = 1 * 1024 * 1024;

package/src/domain/skill/controller.ts

@@ -70,8 +70,10 @@ import { newPipeline } from "../../pipeline/pipeline.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
 import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
 import { RequestContext } from "../../pipeline/request-context.js";
-import { authorizeResolvedResource,
-  newAuthorizeStep } from "../../pipeline/steps/authorize.js";
+import {
+  authorizeResolvedResource,
+  newAuthorizeStep,
+} from "../../pipeline/steps/authorize.js";
 import { newAuthorizeVisibilityTransitionStep } from "../../pipeline/steps/visibility-gates.js";
 import {
   newCleanupIamPoliciesStep,
@@ -80,7 +82,6 @@ import {
 } from "../../pipeline/steps/authorization-tuples.js";
 import { setAuditFieldsForUpdate } from "../../pipeline/steps/defaults.js";
 import {
-  RESOURCE_ID_KEY,
   newDeleteResourceStep,
   newExtractResourceIdStep,
   newLoadExistingForDeleteStep,
@@ -91,11 +92,15 @@ import {
   TARGET_RESOURCE_KEY,
   newLoadTargetStep,
 } from "../../pipeline/steps/load-target.js";
+import { newGuardPluginManagedStep } from "../../pipeline/steps/guard-plugin-managed.js";
+import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
 import { newValidateProtoStep } from "../../pipeline/steps/validation.js";
 import { newValidateVisibilityUpdateStep } from "../../pipeline/steps/validate-visibility.js";
+import { newDeleteVersionArchivesStep } from "../../pipeline/steps/version-archive.js";
 import type { Store } from "../../store/interface.js";
 import { MAX_ZIP_SIZE, TRANSFER_LANE_NOT_CONFIGURED } from "./constants.js";
 import {
+  EXISTING_SKILL_KEY,
   SKILL_KEY,
   newArchiveCurrentSkillStep,
   newBuildInitialSkillStep,
@@ -189,8 +194,9 @@ function kindOf(ctx: HandlerContext): ApiResourceKind {
 }
 
 /**
- * Push — the 12-step upsert-by-slug pipeline (push.ts holds the steps and
- * the versioning discipline). Returns the built skill from context: the
+ * Push — the upsert-by-slug pipeline (push.ts holds the steps and the
+ * versioning discipline; GuardReservedLabels is spliced here because the
+ * request's labels persist). Returns the built skill from context: the
  * pipeline's message type is the request, so the resource rides SKILL_KEY.
  *
  * `method` is the AUTHORIZING descriptor, passed by the caller because two
@@ -220,9 +226,30 @@ async function push(
     .addStep(newExtractAndHashArtifactStep())
     .addStep(newResolveSlugForPushStep())
     .addStep(newFindExistingBySlugStep(deps.store))
+    // A skill has no update RPC: a second push under the same name IS the
+    // client's mutation path, so a plugin-managed skill refuses it here,
+    // naming the plugin. The controller's own re-materialisation passes by
+    // origin.
+    .addStep(
+      newGuardPluginManagedStep<typeof PushSkillRequestSchema>(deps.store, {
+        existingKey: EXISTING_SKILL_KEY,
+      }),
+    )
     .addStep(newGenerateIdIfNeededStep())
     .addStep(newCheckAndStoreArtifactStep(deps.artifactStorage))
     .addStep(newPopulateSkillFieldsStep())
+    // The reserved-namespace guard every write boundary runs, positioned
+    // after the populate step because the skill rides SKILL_KEY (not
+    // newState) and its stored labels ride EXISTING_SKILL_KEY.
+    .addStep(
+      newGuardReservedLabelsStep<typeof PushSkillRequestSchema>(
+        deps.authorizer,
+        {
+          stateOf: (stepCtx) => stepCtx.get(SKILL_KEY) as Skill | undefined,
+          existingKey: EXISTING_SKILL_KEY,
+        },
+      ),
+    )
     .addStep(newArchiveCurrentSkillStep(deps.store, deps.logger))
     .addStep(newStoreSkillStep(deps.store))
     .addStep(
@@ -415,6 +442,11 @@ async function updateVisibility(
     )
     .addStep(newValidateProtoStep())
     .addStep(newLoadSkillForVisibilityUpdateStep(deps.store))
+    .addStep(
+      newGuardPluginManagedStep(deps.store, {
+        existingKey: UPDATE_VISIBILITY_SKILL_KEY,
+      }),
+    )
     .addStep(newRecordVisibilityBeforeUpdateStep(UPDATE_VISIBILITY_SKILL_KEY))
     .addStep(newValidateVisibilityUpdateStep())
     .addStep(
@@ -562,6 +594,7 @@ async function deleteSkill(
     .addStep(newValidateProtoStep())
     .addStep(newExtractResourceIdStep())
     .addStep(newLoadExistingForDeleteStep(deps.store, SkillSchema))
+    .addStep(newGuardPluginManagedStep(deps.store))
     .addStep(newDeleteSkillArchivesStep(deps.store, deps.logger))
     .addStep(newDeleteResourceStep(deps.store))
     .addStep(
@@ -583,42 +616,17 @@ async function deleteSkill(
 
 /**
  * DeleteSkillArchives — best-effort audit cleanup (Go
- * DeleteSkillArchivesStep): failures log and never block the delete.
+ * DeleteSkillArchivesStep): failures log and never block the delete. The
+ * mechanics are the shared content-addressed step's.
  */
 function newDeleteSkillArchivesStep(
   store: Store,
   logger: Logger,
 ): PipelineStep<typeof SkillCommandController.method.delete.input> {
-  return {
-    name: "DeleteSkillArchives",
-    async execute(
-      ctx: RequestContext<typeof SkillCommandController.method.delete.input>,
-    ): 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)",
-        );
-      }
-      try {
-        const deletedCount = await store.deleteAuditByResourceId(
-          ctx.apiResourceKind,
-          resourceId,
-        );
-        if (deletedCount > 0) {
-          logger.info("Deleted archive records for skill", {
-            skillId: resourceId,
-            count: deletedCount,
-          });
-        }
-      } catch (error) {
-        logger.warn("failed to delete skill archives (best-effort)", {
-          skillId: resourceId,
-          error: error instanceof Error ? error.message : String(error),
-        });
-      }
-    },
-  };
+  return newDeleteVersionArchivesStep(store, logger, {
+    stepName: "DeleteSkillArchives",
+    noun: "skill",
+  });
 }
 
 /** Get — the standard LoadTarget-by-id pipeline. */

package/src/domain/skill/push.ts

@@ -7,10 +7,14 @@
  *   ValidateProto → ResolveArtifactSource → BuildInitialSkill →
  *   ExtractAndHashArtifact → ResolveSlugForPush → FindExistingBySlug →
  *   GenerateIDIfNeeded → CheckAndStoreArtifact → PopulateSkillFields →
- *   ArchiveCurrentSkill → StoreSkill → IndexSkillSearch
+ *   GuardReservedLabels → ArchiveCurrentSkill → StoreSkill →
+ *   IndexSkillSearch
  *
- * Step names and context keys are Go's, verbatim. The load-bearing
- * semantics, all preserved:
+ * Step names and context keys are Go's, verbatim; GuardReservedLabels
+ * joined when PushSkillRequest gained `labels` (a plugin materialises its
+ * skills with the plugin label through this chain, so the chain must run
+ * the same reserved-namespace guard every other write boundary runs). The
+ * load-bearing semantics, all preserved:
  *   - exactly one artifact source (inline bytes XOR upload ref — proto
  *     CEL); a staged ref is consumed (retired) whatever happens downstream;
  *   - content addressing: same bytes = same SHA-256 = one stored copy;
@@ -52,11 +56,7 @@ import {
   defaultVisibilityFor,
   getIdPrefix,
 } from "../../pipeline/apiresource-meta.js";
-import {
-  failedPreconditionError,
-  internalError,
-  invalidArgumentError,
-} from "../../pipeline/errors.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
 import type { RequestContext } from "../../pipeline/request-context.js";
 import {
@@ -70,7 +70,11 @@ import {
 } from "../../pipeline/steps/defaults.js";
 import { findResourceBySlug } from "../../pipeline/steps/helpers.js";
 import { generateSlug } from "../../pipeline/steps/slug.js";
-import { AuditNotFoundError } from "../../store/interface.js";
+import {
+  ARTIFACT_BYTES_KEY,
+  newResolveArtifactSourceStep as newSharedResolveArtifactSourceStep,
+} from "../../pipeline/steps/resolve-artifact-source.js";
+import { newArchiveCurrentVersionStep } from "../../pipeline/steps/version-archive.js";
 import type { Store } from "../../store/interface.js";
 import { TRANSFER_LANE_NOT_CONFIGURED } from "./constants.js";
 import { skillSearchExtractor } from "./search-extractor.js";
@@ -83,49 +87,27 @@ type PushDesc = typeof PushSkillRequestSchema;
 
 // Context keys for the push operation (Go push.go, verbatim).
 export const SKILL_KEY = "skill";
-export const ARTIFACT_BYTES_KEY = "pushArtifactBytes";
+export { ARTIFACT_BYTES_KEY };
 export const EXTRACT_RESULT_KEY = "extractResult";
 export const ARTIFACT_STORAGE_KEY_KEY = "artifactStorageKey";
 export const EXISTING_SKILL_KEY = "existingSkill";
 export const SHOULD_CREATE_SKILL_KEY = "shouldCreateSkill";
 
 /**
- * ResolveArtifactSource — materializes the artifact ZIP bytes from
- * whichever source the request carries (proto validation has already
- * guaranteed exactly one): inline bytes pass through; an upload ref is
- * consumed HERE, which retires the single-use reference regardless of how
- * the rest of the pipeline fares. Downstream steps read ARTIFACT_BYTES_KEY
- * and never touch the request's artifact field, so the two sources are
- * indistinguishable past this point.
+ * ResolveArtifactSource — the shared step bound to PushSkillRequest's two
+ * sources and the skill lane's FailedPrecondition copy (see
+ * pipeline/steps/resolve-artifact-source.ts for the semantics).
  */
 export function newResolveArtifactSourceStep(
   slots: UploadSlots | undefined,
 ): PipelineStep<PushDesc> {
-  return {
-    name: "ResolveArtifactSource",
-    async execute(ctx: RequestContext<PushDesc>): Promise<void> {
-      const req = ctx.input;
-      if (req.artifactUploadRef === "") {
-        ctx.set(ARTIFACT_BYTES_KEY, req.artifact);
-        return;
-      }
-      if (slots === undefined) {
-        throw failedPreconditionError(TRANSFER_LANE_NOT_CONFIGURED);
-      }
-      let data: Uint8Array;
-      try {
-        data = await slots.consume(req.artifactUploadRef);
-      } catch (error) {
-        // The reference is client-supplied state, not server fault:
-        // unknown, expired, already consumed, or minted-but-never-uploaded
-        // all mean the client must re-mint and re-upload.
-        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);
-    },
-  };
+  return newSharedResolveArtifactSourceStep<PushDesc>(slots, {
+    source: (req) => ({
+      artifact: req.artifact,
+      artifactUploadRef: req.artifactUploadRef,
+    }),
+    laneNotConfigured: TRANSFER_LANE_NOT_CONFIGURED,
+  });
 }
 
 /**
@@ -138,10 +120,16 @@ export function newBuildInitialSkillStep(): PipelineStep<PushDesc> {
     name: "BuildInitialSkill",
     execute(ctx: RequestContext<PushDesc>): void {
       const req = ctx.input;
+      // The request's labels ARE the skill's labels (replace, never merge):
+      // a push is the skill's definition. GuardReservedLabels, spliced after
+      // FindExistingBySlug, judges them against the stored skill's.
       const skill = create(SkillSchema, {
         apiVersion: "agentic.stigmer.ai/v1",
         kind: "Skill",
-        metadata: create(ApiResourceMetadataSchema, { org: req.org }),
+        metadata: create(ApiResourceMetadataSchema, {
+          org: req.org,
+          labels: { ...req.labels },
+        }),
         spec: create(SkillSpecSchema, { tag: req.tag }),
         status: create(SkillStatusSchema, { state: SkillState.READY }),
       });
@@ -306,6 +294,13 @@ export function newPopulateSkillFieldsStep(): PipelineStep<PushDesc> {
       skill.spec!.name = extractResult.name;
       skill.spec!.description = extractResult.description;
 
+      // A push IS the skill's definition: the labels it carries are the
+      // labels the skill has (replace, never merge), so a re-push that
+      // omits a label removes it — the apply chains' BuildUpdateState
+      // posture. The reserved namespace is judged by GuardReservedLabels
+      // right after this step, against the stored skill's labels.
+      skill.metadata!.labels = { ...req.labels };
+
       if (
         skill.metadata!.visibility ===
         ApiResourceVisibility.api_resource_visibility_unspecified
@@ -360,126 +355,36 @@ export function newPopulateSkillFieldsStep(): PipelineStep<PushDesc> {
  * ArchiveCurrentSkill — the versioning heart (#341/#475): repoint or
  * archive, then the single-holder tag assignment, each with its safe
  * degradation (see the module doc). Runs AFTER PopulateSkillFields so the
- * archived snapshot is the fully-populated head.
+ * archived snapshot is the fully-populated head. The mechanism is the
+ * shared version-archive step; this binding says where a skill keeps its
+ * hash (status.version_hash, mirrored in metadata.version.id) and its tag
+ * (spec.tag).
  */
 export function newArchiveCurrentSkillStep(
   store: Store,
   logger: Logger,
 ): PipelineStep<PushDesc> {
-  return {
-    name: "ArchiveCurrentSkill",
-    async execute(ctx: RequestContext<PushDesc>): Promise<void> {
-      const skill = ctx.get(SKILL_KEY) as Skill;
-      const versionHash = skill.status?.versionHash ?? "";
-      if (versionHash === "") {
-        return;
-      }
-      const tag = skill.spec?.tag ?? "";
-      const skillId = skill.metadata!.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,
-          skillId,
-          versionHash,
-          SkillSchema,
-        );
-        alreadyArchived = true;
-      } catch (error) {
-        if (!(error instanceof AuditNotFoundError)) {
-          logger.warn(
-            "Could not check for an existing archived skill version — archiving anyway",
-            {
-              skillId,
-              versionHash,
-              error: error instanceof Error ? error.message : String(error),
-            },
-          );
+  return newArchiveCurrentVersionStep<typeof SkillSchema, PushDesc>(
+    store,
+    logger,
+    {
+      stepName: "ArchiveCurrentSkill",
+      resourceKey: SKILL_KEY,
+      schema: SkillSchema,
+      noun: "skill",
+      headHashOf: (skill) => skill.status?.versionHash ?? "",
+      clearHeadHash: (skill) => {
+        skill.status!.versionHash = "";
+        if (skill.metadata?.version !== undefined) {
+          skill.metadata.version.id = "";
         }
-      }
-
-      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,
-            skillId,
-            SkillSchema,
-            skill,
-            versionHash,
-            "",
-          );
-        } catch (error) {
-          logger.error(
-            "Failed to archive skill version — reverting the version hash to maintain the audit-resolvability invariant",
-            {
-              skillId,
-              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.
-          skill.status!.versionHash = "";
-          if (skill.metadata?.version !== undefined) {
-            skill.metadata.version.id = "";
-          }
-          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,
-            skillId,
-            versionHash,
-            tag,
-          );
-        } catch (error) {
-          logger.error(
-            "Archived skill version but failed to assign its tag — clearing the live tag to stay consistent with the audit column",
-            {
-              skillId,
-              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.
-          skill.spec!.tag = "";
-        }
-      }
-
-      if (alreadyArchived) {
-        logger.info(
-          "Skill version content already archived — repointed head without a new history row",
-          { skillId, versionHash, tag },
-        );
-      } else {
-        logger.info("Archived skill version to audit history", {
-          skillId,
-          versionHash,
-          tag,
-        });
-      }
+      },
+      liveTagOf: (skill) => skill.spec?.tag ?? "",
+      clearLiveTag: (skill) => {
+        skill.spec!.tag = "";
+      },
     },
-  };
+  );
 }
 
 /** StoreSkill — persists the fully populated head. */

package/src/domain/skill/search-extractor.ts

@@ -55,7 +55,9 @@ export const skillSearchExtractor: SearchableExtractor = {
       org: metadata.org,
       // The enum NAME string, exactly Go's visibility.String().
       visibility: ApiResourceVisibility[metadata.visibility] ?? "",
-      createdAt: Number(skill.status?.audit?.specAudit?.createdAt?.seconds ?? 0n),
+      createdAt: Number(
+        skill.status?.audit?.specAudit?.createdAt?.seconds ?? 0n,
+      ),
     };
   },
 };