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

package/src/domain/skill/version-resolution.ts

@@ -1,27 +1,19 @@
 /**
- * Skill version resolution — ports pkg/domain/skill/controller/
- * load_skill_by_reference.go and list_versions.go: the getByReference
- * version ladder and the paginated version history.
- *
- * The ladder (Go LoadSkillByReferenceStep): resolve the live head by
- * slug+org; empty/"latest" returns it; a 64-hex version matches the head's
- * hash or falls to the indexed audit-by-hash lookup; anything else is a
- * tag, matching the head's live spec.tag first (honest under the
- * single-holder model: push reconciles the live tag with the audit tag
- * column, clearing spec.tag when assignment fails) and then the indexed
- * audit-by-tag lookup.
- *
- * listVersions marks is_current by HEAD-HASH match, not recency: under
- * repoint semantics (#475) re-pushing archived content re-activates its
- * existing row, so the current version need not be the newest-archived
- * one. Tags come from the audit COLUMN (the single-holder source of
- * truth), never from the snapshot — snapshots archive tagless and a legacy
- * snapshot's embedded tag may have moved since it was written.
+ * Skill version resolution — the skill binding of the shared
+ * content-addressed version steps (pipeline/steps/version-history.ts): the
+ * getByReference version ladder and the paginated version history, ported
+ * from pkg/domain/skill/controller/load_skill_by_reference.go and
+ * list_versions.go. The ladder, the is_current rule and the pagination
+ * live in the shared module since plugins needed the identical shape; what
+ * is a skill's is here: the schema, the noun in sentences, the head hash in
+ * status.version_hash, the live tag in spec.tag, and the SkillVersionEntry
+ * mapping (pushed_at/pushed_by prefer the spec-audit updated stamps and fall
+ * back to created, because first pushes only carry created).
  *
  * Proven by __tests__/skill.test.ts's ladder and pagination blocks and
  * the conformance suite's getByReference/listVersions blocks.
  */
-import { create, fromBinary } from "@bufbuild/protobuf";
+import { create } from "@bufbuild/protobuf";
 
 import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
@@ -30,284 +22,90 @@ import {
   ListSkillVersionsResponseSchema,
   SkillVersionEntrySchema,
 } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
-import type { SkillVersionEntry } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import type {
+  ListSkillVersionsResponse,
+  SkillVersionEntry,
+} from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
-import {
-  internalError,
-  invalidArgumentError,
-  notFoundError,
-} from "../../pipeline/errors.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
-import type { RequestContext } from "../../pipeline/request-context.js";
-import { findResourceBySlug, requireOrgForReference } from "../../pipeline/steps/helpers.js";
-import { TARGET_RESOURCE_KEY } from "../../pipeline/steps/load-target.js";
-import { AuditNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
-
-/** A 64-character lowercase-hex string (a SHA-256 content hash). */
-const HASH_PATTERN = /^[a-f0-9]{64}$/;
-
-function isHash(version: string): boolean {
-  return HASH_PATTERN.test(version);
-}
+import {
+  LIST_VERSIONS_HEAD_HASH_KEY,
+  LIST_VERSIONS_RESOURCE_ID_KEY,
+  LIST_VERSIONS_RESPONSE_KEY,
+  newLoadAndMapVersionsStep as newSharedLoadAndMapVersionsStep,
+  newLoadByReferenceWithVersionStep,
+  newResolveBySlugForVersionsStep,
+} from "../../pipeline/steps/version-history.js";
+import type { VersionHistoryBinding } from "../../pipeline/steps/version-history.js";
+
+/** The context keys the controller's mid-chain authorize step reads. */
+export const LIST_VERSIONS_SKILL_ID_KEY = LIST_VERSIONS_RESOURCE_ID_KEY;
+export { LIST_VERSIONS_HEAD_HASH_KEY, LIST_VERSIONS_RESPONSE_KEY };
 
 type GetByReferenceDesc =
   typeof SkillQueryController.method.getByReference.input;
+type ListVersionsDesc = typeof SkillQueryController.method.listVersions.input;
+
+/** Where a skill keeps its hash and its tag, and how its history renders. */
+const skillVersionBinding: VersionHistoryBinding<
+  typeof SkillSchema,
+  ListVersionsDesc,
+  SkillVersionEntry,
+  ListSkillVersionsResponse
+> = {
+  kind: ApiResourceKind.skill,
+  schema: SkillSchema,
+  noun: "skill",
+  headHashOf: (skill) => skill.status?.versionHash ?? "",
+  liveTagOf: (skill) => skill.spec?.tag ?? "",
+  input: (req) => req,
+  mapEntry: mapSkillToVersionEntry,
+  response: (versions, nextPageToken, totalCount) =>
+    create(ListSkillVersionsResponseSchema, {
+      versions,
+      nextPageToken,
+      totalCount,
+    }),
+};
 
 /** Go LoadSkillByReferenceStep — the reference + version ladder. */
 export function newLoadSkillByReferenceStep(
   store: Store,
 ): PipelineStep<GetByReferenceDesc> {
-  return {
-    name: "LoadSkillByReference",
-    async execute(ctx: RequestContext<GetByReferenceDesc>): Promise<void> {
-      const ref = ctx.input;
-
-      if (ref.slug === "") {
-        throw invalidArgumentError("slug is required in reference");
-      }
-
-      // Skill is org-scoped: its slug is unique only within an org, so an
-      // empty-org reference is under-specified.
-      requireOrgForReference(ctx.apiResourceKind, ref.org);
-
-      if (
-        ref.kind !== ApiResourceKind.api_resource_kind_unknown &&
-        ref.kind !== ApiResourceKind.skill
-      ) {
-        throw invalidArgumentError(
-          `kind mismatch: expected ${ApiResourceKind[ApiResourceKind.skill]}, got ${ApiResourceKind[ref.kind]}`,
-        );
-      }
-
-      let mainSkill: Skill | undefined;
-      try {
-        mainSkill = await findResourceBySlug(
-          store,
-          ctx.apiResourceKind,
-          SkillSchema,
-          ref.slug,
-          ref.org,
-        );
-      } catch (error) {
-        throw internalError(error, "failed to list skills");
-      }
-      if (mainSkill === undefined) {
-        throw notFoundError("skill", ref.slug);
-      }
-
-      const version = ref.version.trim();
-      if (version === "" || version === "latest") {
-        ctx.set(TARGET_RESOURCE_KEY, mainSkill);
-        return;
-      }
-
-      if (skillMatchesVersion(mainSkill, version)) {
-        ctx.set(TARGET_RESOURCE_KEY, mainSkill);
-        return;
-      }
-
-      const auditSkill = await findAuditSkillByVersion(
-        store,
-        ctx.apiResourceKind,
-        mainSkill.metadata!.id,
-        version,
-      );
-      if (auditSkill === undefined) {
-        throw notFoundError("skill version", `${ref.slug}:${version}`);
-      }
-      ctx.set(TARGET_RESOURCE_KEY, auditSkill);
-    },
-  };
-}
-
-/**
- * Whether the live head IS the requested version — by hash, or by its
- * live spec.tag (honest under the single-holder tag model, see module doc).
- */
-function skillMatchesVersion(skill: Skill, version: string): boolean {
-  if (skill.status === undefined) {
-    return false;
-  }
-  if (isHash(version)) {
-    return skill.status.versionHash === version;
-  }
-  return skill.spec !== undefined && skill.spec.tag === version;
+  return newLoadByReferenceWithVersionStep(
+    store,
+    skillVersionBinding,
+    "LoadSkillByReference",
+  );
 }
 
-/**
- * Indexed audit lookup by hash or tag (Go findAuditSkillByVersion) —
- * not-found is a normal outcome (undefined), storage failures are
- * Internal.
- */
-async function findAuditSkillByVersion(
-  store: Store,
-  kind: ApiResourceKind,
-  skillId: string,
-  version: string,
-): Promise<Skill | undefined> {
-  if (isHash(version)) {
-    try {
-      return await store.getAuditByHash(kind, skillId, version, SkillSchema);
-    } catch (error) {
-      if (error instanceof AuditNotFoundError) {
-        return undefined;
-      }
-      throw internalError(error, "failed to query audit by hash");
-    }
-  }
-  try {
-    return await store.getAuditByTag(kind, skillId, version, SkillSchema);
-  } catch (error) {
-    if (error instanceof AuditNotFoundError) {
-      return undefined;
-    }
-    throw internalError(error, "failed to query audit by tag");
-  }
-}
-
-// ─── listVersions ────────────────────────────────────────────────────────
-
-const DEFAULT_PAGE_SIZE = 50;
-const MAX_PAGE_SIZE = 100;
-
-export const LIST_VERSIONS_SKILL_ID_KEY = "listVersionsSkillId";
-export const LIST_VERSIONS_HEAD_HASH_KEY = "listVersionsHeadHash";
-export const LIST_VERSIONS_RESPONSE_KEY = "listVersionsResponse";
-
-type ListVersionsDesc = typeof SkillQueryController.method.listVersions.input;
-
 /** Go ResolveSkillBySlugStep — resolves the skill and captures the head hash. */
 export function newResolveSkillBySlugStep(
   store: Store,
 ): PipelineStep<ListVersionsDesc> {
-  return {
-    name: "ResolveSkillBySlug",
-    async execute(ctx: RequestContext<ListVersionsDesc>): Promise<void> {
-      const req = ctx.input;
-      let skill: Skill | undefined;
-      try {
-        skill = await findResourceBySlug(
-          store,
-          ctx.apiResourceKind,
-          SkillSchema,
-          req.slug,
-          req.org,
-        );
-      } catch (error) {
-        throw internalError(error, "failed to search for skill");
-      }
-      if (skill === undefined) {
-        throw notFoundError("skill", `${req.slug} (org: ${req.org})`);
-      }
-      ctx.set(LIST_VERSIONS_SKILL_ID_KEY, skill.metadata!.id);
-      // The live head's hash decides is_current downstream. Under repoint
-      // semantics the current version need not be the newest-archived row,
-      // so recency cannot stand in for currency.
-      ctx.set(LIST_VERSIONS_HEAD_HASH_KEY, skill.status?.versionHash ?? "");
-    },
-  };
+  return newResolveBySlugForVersionsStep(
+    store,
+    skillVersionBinding,
+    "ResolveSkillBySlug",
+  );
 }
 
 /** Go LoadAndMapVersionsStep — audit records → entries → one page. */
 export function newLoadAndMapVersionsStep(
   store: Store,
 ): PipelineStep<ListVersionsDesc> {
-  return {
-    name: "LoadAndMapVersions",
-    async execute(ctx: RequestContext<ListVersionsDesc>): Promise<void> {
-      const req = ctx.input;
-      const skillId = ctx.get(LIST_VERSIONS_SKILL_ID_KEY) as string;
-
-      let records;
-      try {
-        records = await store.listAuditRecords(ctx.apiResourceKind, skillId);
-      } catch (error) {
-        throw internalError(error, "failed to load version history");
-      }
-
-      // is_current = the entry whose hash matches the live head, not the
-      // newest row. Legacy data may hold duplicate-hash rows (predating
-      // repoint semantics); marking only the first match keeps
-      // exactly-one-current true for them too.
-      const headHash = ctx.get(LIST_VERSIONS_HEAD_HASH_KEY) as string;
-      let currentMarked = false;
-      const entries: SkillVersionEntry[] = [];
-      for (const record of records) {
-        let skill: Skill;
-        try {
-          skill = fromBinary(SkillSchema, record.data);
-        } catch {
-          continue;
-        }
-        const isCurrent: boolean =
-          !currentMarked &&
-          headHash !== "" &&
-          (skill.status?.versionHash ?? "") === headHash;
-        currentMarked = currentMarked || isCurrent;
-        // Tag comes from the audit column (source of truth), not the snapshot.
-        entries.push(mapSkillToVersionEntry(skill, isCurrent, record.tag));
-      }
-
-      let pageSize = req.pageSize;
-      if (pageSize <= 0) {
-        pageSize = DEFAULT_PAGE_SIZE;
-      }
-      if (pageSize > MAX_PAGE_SIZE) {
-        pageSize = MAX_PAGE_SIZE;
-      }
-
-      let startIndex = 0;
-      if (req.pageToken !== "") {
-        startIndex = decodePageToken(req.pageToken);
-      }
-
-      let pageEntries: SkillVersionEntry[] = [];
-      let nextPageToken = "";
-      if (startIndex < entries.length) {
-        const end = Math.min(startIndex + pageSize, entries.length);
-        pageEntries = entries.slice(startIndex, end);
-        if (end < entries.length) {
-          nextPageToken = Buffer.from(String(end)).toString("base64");
-        }
-      }
-
-      ctx.set(
-        LIST_VERSIONS_RESPONSE_KEY,
-        create(ListSkillVersionsResponseSchema, {
-          versions: pageEntries,
-          nextPageToken,
-          totalCount: entries.length,
-        }),
-      );
-    },
-  };
-}
-
-/**
- * Decodes the base64 cursor with Go's strictness: base64.StdEncoding
- * rejects malformed input and strconv.Atoi rejects trailing garbage —
- * Buffer.from is lenient on both, so validity is checked explicitly.
- */
-function decodePageToken(token: string): number {
-  const decoded = Buffer.from(token, "base64");
-  if (decoded.toString("base64") !== token) {
-    throw invalidArgumentError("invalid page_token");
-  }
-  const text = decoded.toString("utf8");
-  const index = Number.parseInt(text, 10);
-  if (!Number.isSafeInteger(index) || String(index) !== text || index < 0) {
-    throw invalidArgumentError("invalid page_token");
-  }
-  return index;
+  return newSharedLoadAndMapVersionsStep(
+    store,
+    skillVersionBinding,
+    "LoadAndMapVersions",
+  );
 }
 
 /**
  * Maps an archived Skill snapshot to a version entry (Go
- * mapSkillToVersionEntry). pushed_at/pushed_by prefer the spec-audit
- * updated stamps and fall back to created (first pushes only carry
- * created).
+ * mapSkillToVersionEntry).
  */
 function mapSkillToVersionEntry(
   skill: Skill,

package/src/domain/workflow/controller.ts

@@ -102,6 +102,7 @@ import {
   EXISTING_RESOURCE_KEY,
   newLoadExistingStep,
 } from "../../pipeline/steps/load-existing.js";
+import { newGuardPluginManagedStep } from "../../pipeline/steps/guard-plugin-managed.js";
 import {
   SHOULD_CREATE_KEY,
   newLoadForApplyStep,
@@ -296,6 +297,10 @@ async function update(
     .addStep(newValidateWorkflowSpecStep(deps.validator, deps.logger))
     .addStep(newResolveSlugStep())
     .addStep(newLoadExistingStep(deps.store))
+    // A resource a plugin materialised is the plugin's to redefine; a client
+    // write is refused naming the plugin (GuardPluginManaged, keyed on the
+    // STORED labels and the plugin row's existence).
+    .addStep(newGuardPluginManagedStep(deps.store))
     .addStep(newBuildUpdateStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
     .addStep(newNormalizeReferencesStep())
@@ -381,6 +386,7 @@ async function deleteWorkflow(
     .addStep(newValidateProtoStep())
     .addStep(newExtractResourceIdStep())
     .addStep(newLoadExistingForDeleteStep(deps.store, WorkflowSchema))
+    .addStep(newGuardPluginManagedStep(deps.store))
     .addStep(newCascadeDeleteWorkflowInstancesStep(deps.store, deps.logger))
     .addStep(newDeleteResourceStep(deps.store))
     .addStep(
@@ -436,6 +442,11 @@ async function updateVisibility(
     )
     .addStep(newValidateProtoStep())
     .addStep(newLoadWorkflowForVisibilityUpdateStep(deps.store))
+    .addStep(
+      newGuardPluginManagedStep(deps.store, {
+        existingKey: UPDATE_VISIBILITY_WORKFLOW_KEY,
+      }),
+    )
     .addStep(
       newRecordVisibilityBeforeUpdateStep(UPDATE_VISIBILITY_WORKFLOW_KEY),
     )
@@ -664,6 +675,14 @@ async function tagVersion(
       ),
     )
     .addStep(newValidateProtoStep())
+    .addStep(newLoadWorkflowForTagVersionStep(deps.store))
+    // Moving a tag redefines which version a plugin-managed workflow
+    // advertises; the plugin owns that, so a client is refused naming it.
+    .addStep(
+      newGuardPluginManagedStep(deps.store, {
+        existingKey: TAG_VERSION_WORKFLOW_KEY,
+      }),
+    )
     .addStep(newTagWorkflowVersionStep(deps.store))
     .build()
     .execute(reqCtx);
@@ -671,13 +690,17 @@ async function tagVersion(
   return reqCtx.get(TAG_VERSION_RESULT_KEY) as Workflow;
 }
 
-function newTagWorkflowVersionStep(store: Store): PipelineStep<TagVersionDesc> {
+/** The live workflow the tag move targets, loaded once for the guard and the move. */
+const TAG_VERSION_WORKFLOW_KEY = "tagVersionWorkflow";
+
+/** Loads the live workflow to confirm it exists; the tag step learns its head hash from it. */
+function newLoadWorkflowForTagVersionStep(
+  store: Store,
+): PipelineStep<TagVersionDesc> {
   return {
-    name: "TagWorkflowVersion",
+    name: "LoadWorkflowForTagVersion",
     async execute(ctx: RequestContext<TagVersionDesc>): Promise<void> {
       const req = ctx.input;
-
-      // Load the live workflow to confirm it exists and learn its head hash.
       let workflow: Workflow;
       try {
         workflow = await store.getResource(
@@ -691,6 +714,17 @@ function newTagWorkflowVersionStep(store: Store): PipelineStep<TagVersionDesc> {
         }
         throw internalError(error, "failed to load workflow");
       }
+      ctx.set(TAG_VERSION_WORKFLOW_KEY, workflow);
+    },
+  };
+}
+
+function newTagWorkflowVersionStep(store: Store): PipelineStep<TagVersionDesc> {
+  return {
+    name: "TagWorkflowVersion",
+    async execute(ctx: RequestContext<TagVersionDesc>): Promise<void> {
+      const req = ctx.input;
+      const workflow = ctx.get(TAG_VERSION_WORKFLOW_KEY) as Workflow;
 
       // Move the tag in the audit store. A version_hash with no audit
       // record yields AuditNotFoundError (the hash-exists check) and leaves

package/src/domain/workflow/registry/data/task-kind-registry.json

@@ -1517,6 +1517,7 @@
                     "execution_context",
                     "schedule",
                     "memory",
+                    "plugin",
                     "project"
                   ],
                   "type": "string"