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

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

@@ -0,0 +1,362 @@
+/**
+ * The read side of content-addressed versioning, shared by every kind whose
+ * version is the SHA-256 of a pushed archive (skills, plugins): the
+ * getByReference version ladder and the paginated version history. Skills
+ * carried both alone (the Go LoadSkillByReferenceStep / ListVersions port);
+ * plugins need the identical ladder over another schema, and a second copy
+ * would be the drift the house forbids, so the steps take a
+ * `VersionedResourceBinding` that names what differs per kind (the schema,
+ * the noun in sentences, where the head hash and the live tag live, how a
+ * snapshot maps to an entry) and keep everything else once.
+ *
+ * The ladder: 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
+ * tag first (honest under the single-holder model: a push reconciles the
+ * live tag with the audit tag column, clearing the live 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.
+ *
+ * Proven by the skill domain's __tests__/skill.test.ts (ladder and
+ * pagination blocks) and the skill and plugin conformance suites'
+ * getByReference/listVersions blocks.
+ */
+import { fromBinary } from "@bufbuild/protobuf";
+import type { DescMessage, Message, MessageShape } from "@bufbuild/protobuf";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+
+import {
+  internalError,
+  invalidArgumentError,
+  notFoundError,
+} from "../errors.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 { findResourceBySlug, requireOrgForReference } from "./helpers.js";
+import { TARGET_RESOURCE_KEY } from "./load-target.js";
+import { metadataOf } from "./shapes.js";
+
+/** A 64-character lowercase-hex string (a SHA-256 content hash). */
+const HASH_PATTERN = /^[a-f0-9]{64}$/;
+
+export function isVersionHash(version: string): boolean {
+  return HASH_PATTERN.test(version);
+}
+
+/** What a content-versioned kind must say about itself for the ladder. */
+export interface VersionedResourceBinding<Desc extends DescMessage> {
+  readonly kind: ApiResourceKind;
+  readonly schema: Desc;
+  /** The noun in sentences: "skill", "plugin". */
+  readonly noun: string;
+  /** The head's content hash (status.version_hash, status.digest). */
+  headHashOf(resource: MessageShape<Desc>): string;
+  /** The tag the live head claims (spec.tag; the plugin's manifest version). */
+  liveTagOf(resource: MessageShape<Desc>): string;
+}
+
+type GetByReferenceDesc = typeof ApiResourceReferenceSchema;
+
+/** The reference + version ladder (Go LoadSkillByReferenceStep, generalised). */
+export function newLoadByReferenceWithVersionStep<Desc extends DescMessage>(
+  store: Store,
+  binding: VersionedResourceBinding<Desc>,
+  stepName: string,
+): PipelineStep<GetByReferenceDesc> {
+  return {
+    name: stepName,
+    async execute(ctx: RequestContext<GetByReferenceDesc>): Promise<void> {
+      const ref = ctx.input;
+
+      if (ref.slug === "") {
+        throw invalidArgumentError("slug is required in reference");
+      }
+
+      // Org-scoped kinds: the 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 !== binding.kind
+      ) {
+        throw invalidArgumentError(
+          `kind mismatch: expected ${ApiResourceKind[binding.kind]}, got ${ApiResourceKind[ref.kind]}`,
+        );
+      }
+
+      let head: MessageShape<Desc> | undefined;
+      try {
+        head = await findResourceBySlug(
+          store,
+          ctx.apiResourceKind,
+          binding.schema,
+          ref.slug,
+          ref.org,
+        );
+      } catch (error) {
+        throw internalError(error, `failed to list ${binding.noun}s`);
+      }
+      if (head === undefined) {
+        throw notFoundError(binding.noun, ref.slug);
+      }
+
+      const version = ref.version.trim();
+      if (version === "" || version === "latest") {
+        ctx.set(TARGET_RESOURCE_KEY, head);
+        return;
+      }
+
+      if (headMatchesVersion(binding, head, version)) {
+        ctx.set(TARGET_RESOURCE_KEY, head);
+        return;
+      }
+
+      const archived = await findAuditByVersion(
+        store,
+        ctx.apiResourceKind,
+        binding.schema,
+        idOf(head),
+        version,
+      );
+      if (archived === undefined) {
+        throw notFoundError(
+          `${binding.noun} version`,
+          `${ref.slug}:${version}`,
+        );
+      }
+      ctx.set(TARGET_RESOURCE_KEY, archived);
+    },
+  };
+}
+
+/** Whether the live head IS the requested version — by hash, or by its live tag. */
+function headMatchesVersion<Desc extends DescMessage>(
+  binding: VersionedResourceBinding<Desc>,
+  head: MessageShape<Desc>,
+  version: string,
+): boolean {
+  if (isVersionHash(version)) {
+    return binding.headHashOf(head) === version;
+  }
+  const liveTag = binding.liveTagOf(head);
+  return liveTag !== "" && liveTag === version;
+}
+
+/**
+ * Indexed audit lookup by hash or tag — not-found is a normal outcome
+ * (undefined), storage failures are Internal.
+ */
+async function findAuditByVersion<Desc extends DescMessage>(
+  store: Store,
+  kind: ApiResourceKind,
+  schema: Desc,
+  resourceId: string,
+  version: string,
+): Promise<MessageShape<Desc> | undefined> {
+  if (isVersionHash(version)) {
+    try {
+      return await store.getAuditByHash(kind, resourceId, version, schema);
+    } catch (error) {
+      if (error instanceof AuditNotFoundError) {
+        return undefined;
+      }
+      throw internalError(error, "failed to query audit by hash");
+    }
+  }
+  try {
+    return await store.getAuditByTag(kind, resourceId, version, schema);
+  } 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_RESOURCE_ID_KEY = "listVersionsResourceId";
+export const LIST_VERSIONS_HEAD_HASH_KEY = "listVersionsHeadHash";
+export const LIST_VERSIONS_RESPONSE_KEY = "listVersionsResponse";
+
+/** The fields every ListVersions input carries; the binding reads them off its own message. */
+export interface ListVersionsInputShape {
+  readonly org: string;
+  readonly slug: string;
+  readonly pageToken: string;
+  readonly pageSize: number;
+}
+
+/** What differs per kind in the version history: the input, the entry, the response. */
+export interface VersionHistoryBinding<
+  Desc extends DescMessage,
+  InputDesc extends DescMessage,
+  Entry extends Message,
+  Response extends Message,
+> extends VersionedResourceBinding<Desc> {
+  input(message: MessageShape<InputDesc>): ListVersionsInputShape;
+  /** An archived snapshot to one entry; `tag` is the audit column's. */
+  mapEntry(
+    snapshot: MessageShape<Desc>,
+    isCurrent: boolean,
+    tag: string,
+  ): Entry;
+  response(
+    entries: Entry[],
+    nextPageToken: string,
+    totalCount: number,
+  ): Response;
+}
+
+/** Resolves the head by slug and captures its id and hash (Go ResolveSkillBySlugStep, generalised). */
+export function newResolveBySlugForVersionsStep<
+  Desc extends DescMessage,
+  InputDesc extends DescMessage,
+  Entry extends Message,
+  Response extends Message,
+>(
+  store: Store,
+  binding: VersionHistoryBinding<Desc, InputDesc, Entry, Response>,
+  stepName: string,
+): PipelineStep<InputDesc> {
+  return {
+    name: stepName,
+    async execute(ctx: RequestContext<InputDesc>): Promise<void> {
+      const req = binding.input(ctx.input);
+      let head: MessageShape<Desc> | undefined;
+      try {
+        head = await findResourceBySlug(
+          store,
+          ctx.apiResourceKind,
+          binding.schema,
+          req.slug,
+          req.org,
+        );
+      } catch (error) {
+        throw internalError(error, `failed to search for ${binding.noun}`);
+      }
+      if (head === undefined) {
+        throw notFoundError(binding.noun, `${req.slug} (org: ${req.org})`);
+      }
+      ctx.set(LIST_VERSIONS_RESOURCE_ID_KEY, idOf(head));
+      // 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, binding.headHashOf(head));
+    },
+  };
+}
+
+/** Audit records → entries → one page (Go LoadAndMapVersionsStep, generalised). */
+export function newLoadAndMapVersionsStep<
+  Desc extends DescMessage,
+  InputDesc extends DescMessage,
+  Entry extends Message,
+  Response extends Message,
+>(
+  store: Store,
+  binding: VersionHistoryBinding<Desc, InputDesc, Entry, Response>,
+  stepName: string,
+): PipelineStep<InputDesc> {
+  return {
+    name: stepName,
+    async execute(ctx: RequestContext<InputDesc>): Promise<void> {
+      const req = binding.input(ctx.input);
+      const resourceId = ctx.get(LIST_VERSIONS_RESOURCE_ID_KEY) as string;
+
+      let records;
+      try {
+        records = await store.listAuditRecords(ctx.apiResourceKind, resourceId);
+      } 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: Entry[] = [];
+      for (const record of records) {
+        let snapshot: MessageShape<Desc>;
+        try {
+          snapshot = fromBinary(binding.schema, record.data);
+        } catch {
+          continue;
+        }
+        const isCurrent: boolean =
+          !currentMarked &&
+          headHash !== "" &&
+          binding.headHashOf(snapshot) === headHash;
+        currentMarked = currentMarked || isCurrent;
+        // Tag comes from the audit column (source of truth), not the snapshot.
+        entries.push(binding.mapEntry(snapshot, 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: Entry[] = [];
+      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,
+        binding.response(pageEntries, nextPageToken, 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.
+ */
+export 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;
+}
+
+/** metadata.id of a resource message; every versioned kind carries the commons metadata. */
+function idOf(resource: Message): string {
+  return metadataOf(resource)?.id ?? "";
+}

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

@@ -46,10 +46,7 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 import type { UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
-import type {
-  Authorizer,
-  AuthzDecision,
-} from "../../extensions/authorizer.js";
+import type { Authorizer, AuthzDecision } from "../../extensions/authorizer.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
 import { internalError } from "../errors.js";
 import type { PipelineStep } from "../pipeline.js";
@@ -92,9 +89,10 @@ export function newGuardPublicVisibilityStep<Desc extends DescMessage>(
  * chain's own context key (every updateVisibility chain stores it —
  * the RecordVisibilityBeforeUpdate pattern).
  */
-export function newAuthorizeVisibilityTransitionStep<
-  Desc extends DescMessage,
->(targetKey: string, authorizer: Authorizer): PipelineStep<Desc> {
+export function newAuthorizeVisibilityTransitionStep<Desc extends DescMessage>(
+  targetKey: string,
+  authorizer: Authorizer,
+): PipelineStep<Desc> {
   return {
     name: "AuthorizeVisibilityTransition",
     async execute(ctx: RequestContext<Desc>): Promise<void> {
@@ -127,8 +125,13 @@ export function newAuthorizeVisibilityTransitionStep<
   };
 }
 
-/** The single owner of "may this caller set public?" — both doors call it. */
-async function requireOperatorMaySetPublic(
+/**
+ * The single owner of "may this caller set public?" — both doors call it,
+ * and so does the plugin push chain, whose requested level rides the
+ * request (the level then flows to every member through the members' own
+ * create and updateVisibility doors, which run this check again).
+ */
+export async function requireOperatorMaySetPublic(
   authorizer: Authorizer,
   caller: CallerIdentity,
 ): Promise<void> {

package/src/query/README.md

@@ -3,7 +3,7 @@
 The two cross-aggregate query services (D4 #14; Go `pkg/query/`):
 
 - `search/` — the SearchService over the store's search index: criteria value object, the
-  searchable-extractor registry (13 kinds, `kind_meta`-derived set), the
+  searchable-extractor registry (14 kinds, `kind_meta`-derived set), the
   query store over `Store.querySearchIndex`, and boot-time RebuildIndex.
 - `activity/` — the ActivityQueryController recents feed: sessions +
   workflow executions merged newest-first (stigmer#461).

package/src/query/search/__tests__/criteria.test.ts

@@ -42,7 +42,7 @@ function criteria(overrides?: {
 }
 
 describe("searchIndexedKinds derivation (kind_meta)", () => {
-  it("derives exactly the 13 searchable kinds, project included", () => {
+  it("derives exactly the 14 searchable kinds, project and plugin included", () => {
     // Go's SearchableKinds map, pinned by its invariant test against the
     // same kind_meta derivation. project rides #14 (DD-D) although its
     // domain ports with #16 — RebuildIndex on an adopted Go database
@@ -62,6 +62,7 @@ describe("searchIndexedKinds derivation (kind_meta)", () => {
         ApiResourceKind.organization,
         ApiResourceKind.workflow_execution,
         ApiResourceKind.workflow_instance,
+        ApiResourceKind.plugin,
       ].sort((a, b) => a - b),
     );
   });
@@ -112,9 +113,7 @@ describe("SearchCriteria normalization (Go NewSearchCriteria)", () => {
   it("rejects a query over the cap with Go's exact message", () => {
     expect(() =>
       criteria({ query: "x".repeat(MAX_QUERY_LENGTH + 1) }),
-    ).toThrowError(
-      "search query exceeds maximum length of 500 characters",
-    );
+    ).toThrowError("search query exceeds maximum length of 500 characters");
   });
 
   it("accepts a query at exactly the cap", () => {
@@ -141,9 +140,9 @@ describe("SearchCriteria normalization (Go NewSearchCriteria)", () => {
 describe("mode selection", () => {
   it("empty kinds is discover mode; requested kinds is not", () => {
     expect(criteria({ kinds: [] }).isDiscoverMode()).toBe(true);
-    expect(
-      criteria({ kinds: [ApiResourceKind.agent] }).isDiscoverMode(),
-    ).toBe(false);
+    expect(criteria({ kinds: [ApiResourceKind.agent] }).isDiscoverMode()).toBe(
+      false,
+    );
   });
 
   it("hasQuery: empty and whitespace-only queries mean list mode", () => {

package/src/query/search/__tests__/query-store.test.ts

@@ -95,7 +95,9 @@ function newSession(
     status: {
       audit: {
         specAudit: {
-          createdAt: { seconds: BigInt(opts?.createdAtSeconds ?? 1_700_000_000) },
+          createdAt: {
+            seconds: BigInt(opts?.createdAtSeconds ?? 1_700_000_000),
+          },
         },
       },
     },
@@ -432,7 +434,12 @@ describe("rebuildIndex", () => {
     const adopted = SqliteStore.open(fixture.dbPath);
     try {
       const project = create(ProjectSchema, {
-        metadata: { id: "prj_1", name: "billing", slug: "billing", org: "acme" },
+        metadata: {
+          id: "prj_1",
+          name: "billing",
+          slug: "billing",
+          org: "acme",
+        },
         spec: { description: "the billing project" },
         status: {
           audit: { specAudit: { createdAt: { seconds: 1_700_000_000n } } },

package/src/query/search/__tests__/registry.test.ts

@@ -78,15 +78,17 @@ describe("SearchableResourceRegistry (Go registry_test.go)", () => {
 
   it("supportedKinds sorts by the kind NAME string (Go's kind.String() sort)", () => {
     const registry = newSearchableResourceRegistry();
-    const names = registry.supportedKinds().map((kind) => ApiResourceKind[kind]);
+    const names = registry
+      .supportedKinds()
+      .map((kind) => ApiResourceKind[kind]);
     expect(names).toEqual([...names].sort((a, b) => a.localeCompare(b)));
   });
 
   it("validateExpectedKinds warns with the missing kinds (never throws)", () => {
     const logger = testLogger();
-    new SearchableResourceRegistry([agentSearchExtractor]).validateExpectedKinds(
-      logger,
-    );
+    new SearchableResourceRegistry([
+      agentSearchExtractor,
+    ]).validateExpectedKinds(logger);
     expect(logger.warns).toHaveLength(1);
     const missing = logger.warns[0]?.missing_kinds as string[];
     expect(missing).toContain("skill");

package/src/query/search/registry.ts

@@ -27,6 +27,7 @@ import { environmentSearchExtractor } from "../../domain/environment/search-extr
 import { executionContextSearchExtractor } from "../../domain/executioncontext/search-extractor.js";
 import { mcpServerSearchExtractor } from "../../domain/mcpserver/search-extractor.js";
 import { organizationSearchExtractor } from "../../domain/organization/search-extractor.js";
+import { pluginSearchExtractor } from "../../domain/plugin/search-extractor.js";
 import { projectSearchExtractor } from "../../domain/project/search-extractor.js";
 import { sessionSearchExtractor } from "../../domain/session/search-extractor.js";
 import { skillSearchExtractor } from "../../domain/skill/search-extractor.js";
@@ -39,7 +40,10 @@ import type { SearchableExtractor } from "./extractor.js";
 
 /** Go SearchableResourceRegistry — kind → extractor, read-only after build. */
 export class SearchableResourceRegistry {
-  private readonly extractors: ReadonlyMap<ApiResourceKind, SearchableExtractor>;
+  private readonly extractors: ReadonlyMap<
+    ApiResourceKind,
+    SearchableExtractor
+  >;
 
   constructor(extractors: readonly SearchableExtractor[]) {
     const map = new Map<ApiResourceKind, SearchableExtractor>();
@@ -111,6 +115,7 @@ export function newSearchableResourceRegistry(): SearchableResourceRegistry {
     executionContextSearchExtractor,
     mcpServerSearchExtractor,
     organizationSearchExtractor,
+    pluginSearchExtractor,
     projectSearchExtractor,
     sessionSearchExtractor,
     skillSearchExtractor,