@openwop/openwop-conformance 1.3.0 → 1.5.0

package/src/scenarios/prompt-pack-install.test.ts

@@ -0,0 +1,187 @@
+/**
+ * prompt-pack-install — RFC 0028 §B boot-time pack-install proof.
+ *
+ * Asserts: when the host advertises
+ * `capabilities.prompts.endpointsSupported: true` AND the in-tree
+ * reference prompt pack (`vendor.openwop.prompt-sample`) was
+ * installed at boot, the pack's two templates (`writer-system`,
+ * `critic-system`) surface in `GET /v1/prompts` carrying
+ * `meta.source: "pack"` + `meta.packName: "vendor.openwop.prompt-sample"`
+ * + `meta.packVersion: "1.0.0"`.
+ *
+ * This is the install-flow regression pin. If the boot-time loader
+ * stops walking `examples/packs/*` or stops calling
+ * `installPackTemplates()`, this scenario fails first — before any
+ * downstream scenario notices missing templates.
+ *
+ * The scenario does NOT mutate state — it relies on the host having
+ * installed at least one prompt pack at startup. RFC 0028 §B does
+ * NOT require a host advertising `endpointsSupported: true` to have
+ * any pack installed (a fresh production host with no pack
+ * subscriptions is conformant); when zero pack-source templates
+ * are listed, the structural assertions on sub-tests 2-3 still run
+ * but the existence claim is treated as a soft skip.
+ *
+ * `OPENWOP_TEST_PROMPT_PACK_INSTALLED=true` is a conformance-runner
+ * (client-side) flag — the operator running the suite sets it when
+ * they know the target host has at least one prompt pack installed,
+ * which promotes the existence claim from soft-skip to hard
+ * assertion. The flag is NOT set by the host itself. When running
+ * against the in-tree workflow-engine sample (which auto-installs
+ * `vendor.openwop.prompt-sample` via `promptPackLoader`), the
+ * operator should set it so the existence path IS exercised.
+ *
+ * Capability-gated: skips when the host doesn't advertise
+ * `capabilities.prompts.endpointsSupported: true`. Under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true`, the gate hardens from SKIP to
+ * FAIL via `behaviorGate('prompts-endpoints', ...)`.
+ *
+ * HTTP-driven: skips when no `OPENWOP_BASE_URL` is configured.
+ *
+ * @see RFCS/0028-prompt-library-endpoints.md §B
+ * @see spec/v1/prompts.md §"Discovery & distribution"
+ * @see examples/packs/prompt-sample/pack.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+
+interface DiscoveryDoc {
+  capabilities?: {
+    prompts?: {
+      supported?: unknown;
+      endpointsSupported?: unknown;
+    };
+  };
+}
+
+interface PromptTemplate {
+  templateId: string;
+  version: string;
+  kind: string;
+  meta?: {
+    source?: 'host' | 'pack' | 'user';
+    packName?: string;
+    packVersion?: string;
+  };
+}
+
+interface ListResponse {
+  items: PromptTemplate[];
+  nextCursor?: string;
+}
+
+async function readDiscovery(): Promise<DiscoveryDoc | null> {
+  const res = await driver.get('/.well-known/openwop');
+  if (res.status !== 200) return null;
+  return res.json as DiscoveryDoc;
+}
+
+function endpointsSupported(d: DiscoveryDoc | null): boolean {
+  return d?.capabilities?.prompts?.endpointsSupported === true;
+}
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const REQUIRE_PACK_INSTALLED = process.env.OPENWOP_TEST_PROMPT_PACK_INSTALLED === 'true';
+
+describe.skipIf(HTTP_SKIP)('prompt-pack-install: boot-time loader surfaces pack templates (RFC 0028 §B)', () => {
+  it('GET /v1/prompts?source=pack returns 200 + an array of PromptTemplate objects when endpointsSupported is advertised', async () => {
+    const d = await readDiscovery();
+    if (!behaviorGate('prompts-endpoints', endpointsSupported(d))) return;
+
+    const res = await driver.get('/v1/prompts?source=pack');
+    expect(
+      res.status,
+      driver.describe(
+        'spec/v1/prompts.md §"Discovery & distribution"',
+        'GET /v1/prompts MUST return 200 when prompts.endpointsSupported is advertised',
+      ),
+    ).toBe(200);
+
+    const body = res.json as ListResponse;
+    expect(
+      Array.isArray(body.items),
+      driver.describe(
+        'RFCS/0028-prompt-library-endpoints.md §A',
+        '`items` MUST be an array of PromptTemplate objects',
+      ),
+    ).toBe(true);
+
+    // Existence claim — only fail when the host explicitly opts in
+    // via OPENWOP_TEST_PROMPT_PACK_INSTALLED. RFC 0028 §B treats
+    // "zero installed packs" as a conformant state for any host that
+    // hasn't subscribed to a pack source.
+    if (REQUIRE_PACK_INSTALLED) {
+      const packItems = body.items.filter((t) => t.meta?.source === 'pack');
+      expect(
+        packItems.length,
+        driver.describe(
+          'RFCS/0028-prompt-library-endpoints.md §B',
+          'OPENWOP_TEST_PROMPT_PACK_INSTALLED=true asserts the boot-time loader installed at least one pack',
+        ),
+      ).toBeGreaterThan(0);
+    }
+  });
+
+  it('each pack-source template carries meta.source/packName/packVersion stamps per RFC 0028 §B', async () => {
+    const d = await readDiscovery();
+    if (!behaviorGate('prompts-endpoints', endpointsSupported(d))) return;
+
+    const res = await driver.get('/v1/prompts?source=pack');
+    if (res.status !== 200) return;
+    const body = res.json as ListResponse;
+    const packItems = body.items.filter((t) => t.meta?.source === 'pack');
+    if (packItems.length === 0) return; // gated above
+
+    for (const t of packItems) {
+      expect(
+        t.meta?.source,
+        driver.describe(
+          'schemas/prompt-template.schema.json §meta.source',
+          'pack-installed templates MUST stamp `meta.source: "pack"`',
+        ),
+      ).toBe('pack');
+      expect(
+        typeof t.meta?.packName === 'string' && (t.meta?.packName?.length ?? 0) > 0,
+        driver.describe(
+          'RFCS/0028-prompt-library-endpoints.md §B',
+          'pack-installed templates MUST stamp `meta.packName`',
+        ),
+      ).toBe(true);
+      expect(
+        typeof t.meta?.packVersion === 'string' && /^\d+\.\d+\.\d+/.test(t.meta?.packVersion ?? ''),
+        driver.describe(
+          'RFCS/0028-prompt-library-endpoints.md §B',
+          'pack-installed templates MUST stamp a semver `meta.packVersion`',
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it('GET /v1/prompts/{templateId} returns a pack-source template by id (reference pack: writer-system)', async () => {
+    const d = await readDiscovery();
+    if (!behaviorGate('prompts-endpoints', endpointsSupported(d))) return;
+
+    const list = await driver.get('/v1/prompts?source=pack');
+    if (list.status !== 200) return;
+    const body = list.json as ListResponse;
+    const writer = body.items.find((t) => t.templateId === 'writer-system' && t.meta?.source === 'pack');
+    if (!writer) return; // host may have installed a different reference pack; skip silently
+
+    const fetched = await driver.get(`/v1/prompts/${encodeURIComponent('writer-system')}`);
+    expect(
+      fetched.status,
+      driver.describe(
+        'RFCS/0028-prompt-library-endpoints.md §A',
+        'GET /v1/prompts/{templateId} MUST return 200 for a known pack-source template id',
+      ),
+    ).toBe(200);
+    const t = fetched.json as PromptTemplate;
+    expect(t.templateId).toBe('writer-system');
+    expect(
+      t.meta?.source,
+      'fetched template MUST preserve `meta.source: "pack"` provenance',
+    ).toBe('pack');
+  });
+});

package/src/scenarios/prompt-render-deterministic.test.ts

@@ -0,0 +1,240 @@
+/**
+ * prompt-render-deterministic — RFC 0028 §A deterministic-hash invariant.
+ *
+ * Asserts: two calls to `POST /v1/prompts:render` with identical
+ * `(ref, variables, contentTrust)` inputs MUST produce identical
+ * `hash` AND identical `variableHashes`. Different variables MUST
+ * produce different `variableHashes` for the changed keys (and a
+ * different overall `hash`). The deterministic-render invariant
+ * mirrors the `prompt.composed` replay invariant per RFC 0027 §F.
+ *
+ * Capability-gated: skips when the host doesn't advertise
+ * `capabilities.prompts.endpointsSupported: true`.
+ *
+ * HTTP-driven: skips when no `OPENWOP_BASE_URL` is configured.
+ *
+ * Under `OPENWOP_REQUIRE_BEHAVIOR=true`, the capability gate hardens
+ * from SKIP to FAIL.
+ *
+ * @see spec/v1/prompts.md §"Discovery & distribution" — Deterministic-render invariant
+ * @see RFCS/0028-prompt-library-endpoints.md §A
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+
+interface DiscoveryDoc {
+  capabilities?: {
+    prompts?: {
+      supported?: unknown;
+      endpointsSupported?: unknown;
+    };
+  };
+}
+
+interface RenderResponse {
+  composed?: string;
+  hash: string;
+  refs: string[];
+  variableHashes: Record<string, string>;
+  contentTrust?: 'trusted' | 'untrusted';
+}
+
+interface PromptTemplate {
+  templateId: string;
+  version: string;
+  kind: string;
+  text: string;
+  variables?: Array<{ name: string; required?: boolean; source?: string }>;
+}
+
+interface ListResponse {
+  items: PromptTemplate[];
+}
+
+async function readDiscovery(): Promise<DiscoveryDoc | null> {
+  const res = await driver.get('/.well-known/openwop');
+  if (res.status !== 200) return null;
+  return res.json as DiscoveryDoc;
+}
+
+function endpointsSupported(d: DiscoveryDoc | null): boolean {
+  return d?.capabilities?.prompts?.endpointsSupported === true;
+}
+
+/** Pick a template that has at least one input-source variable
+ *  (so we can vary the binding). Prefer host-source so we don't
+ *  depend on user-created templates from prior runs. Skip
+ *  secret-source variables — those need BYOK provisioning. */
+async function pickTemplateWithInputVar(): Promise<PromptTemplate | null> {
+  const res = await driver.get('/v1/prompts?source=host&limit=200');
+  if (res.status !== 200) return null;
+  const body = res.json as ListResponse;
+  for (const t of body.items) {
+    const hasInputVar = (t.variables ?? []).some(
+      (v) => v.source !== 'secret' && v.required === true,
+    );
+    if (hasInputVar) return t;
+  }
+  // Fall back: any template (even with no required vars works for the
+  // identity-of-hash assertion; just no negative-control sub-test).
+  return body.items[0] ?? null;
+}
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+describe.skipIf(HTTP_SKIP)('prompt-render-deterministic: hash stable across identical inputs (RFC 0028 §A)', () => {
+  it('identical (ref, variables) inputs produce identical hash + variableHashes', async () => {
+    const d = await readDiscovery();
+    if (!behaviorGate('prompts-endpoints', endpointsSupported(d))) return;
+
+    const template = await pickTemplateWithInputVar();
+    if (!template) return;
+
+    const variableNames = (template.variables ?? [])
+      .filter((v) => v.source !== 'secret')
+      .map((v) => v.name);
+
+    // Build a binding set that satisfies every non-secret variable.
+    const variables: Record<string, unknown> = {};
+    for (const name of variableNames) variables[name] = `conformance-${name}-value`;
+
+    const ref = `prompt:${template.templateId}@${template.version}`;
+    const first = await driver.post('/v1/prompts:render', { ref, variables });
+    if (first.status !== 200) return;
+    const second = await driver.post('/v1/prompts:render', { ref, variables });
+    expect(second.status).toBe(200);
+
+    const a = first.json as RenderResponse;
+    const b = second.json as RenderResponse;
+
+    expect(
+      a.hash,
+      driver.describe(
+        'spec/v1/prompts.md §Discovery & distribution',
+        'render hash MUST be stable across identical (ref, variables) inputs',
+      ),
+    ).toBe(b.hash);
+    expect(
+      Object.keys(a.variableHashes).sort(),
+      driver.describe(
+        'spec/v1/prompts.md §Discovery & distribution',
+        'variableHashes key set MUST be stable',
+      ),
+    ).toEqual(Object.keys(b.variableHashes).sort());
+    for (const k of Object.keys(a.variableHashes)) {
+      expect(a.variableHashes[k]).toBe(b.variableHashes[k]);
+    }
+  });
+
+  it('different variable values produce different hash + at least one different variableHash', async () => {
+    const d = await readDiscovery();
+    if (!behaviorGate('prompts-endpoints', endpointsSupported(d))) return;
+
+    const template = await pickTemplateWithInputVar();
+    if (!template) return;
+    const requiredVars = (template.variables ?? []).filter(
+      (v) => v.source !== 'secret' && v.required === true,
+    );
+    if (requiredVars.length === 0) return; // no required var to toggle
+
+    const variables: Record<string, unknown> = {};
+    for (const v of template.variables ?? []) {
+      if (v.source === 'secret') continue;
+      variables[v.name] = `conformance-${v.name}-baseline`;
+    }
+
+    const ref = `prompt:${template.templateId}@${template.version}`;
+    const baseline = await driver.post('/v1/prompts:render', { ref, variables });
+    if (baseline.status !== 200) return;
+
+    // Toggle one required variable.
+    const toggled = { ...variables, [requiredVars[0]!.name]: 'conformance-toggled-value' };
+    const altered = await driver.post('/v1/prompts:render', { ref, variables: toggled });
+    expect(altered.status).toBe(200);
+
+    const a = baseline.json as RenderResponse;
+    const b = altered.json as RenderResponse;
+
+    expect(
+      a.hash,
+      driver.describe(
+        'spec/v1/prompts.md §Discovery & distribution',
+        'render hash MUST differ when any variable binding differs',
+      ),
+    ).not.toBe(b.hash);
+    expect(
+      a.variableHashes[requiredVars[0]!.name],
+      driver.describe(
+        'spec/v1/prompts.md §Discovery & distribution',
+        'variableHashes[name] MUST differ when name binding differs',
+      ),
+    ).not.toBe(b.variableHashes[requiredVars[0]!.name]);
+  });
+
+  it('hash + variableHashes MUST match sha256:<hex64> pattern', async () => {
+    const d = await readDiscovery();
+    if (!behaviorGate('prompts-endpoints', endpointsSupported(d))) return;
+
+    const template = await pickTemplateWithInputVar();
+    if (!template) return;
+    const variables: Record<string, unknown> = {};
+    for (const v of template.variables ?? []) {
+      if (v.source === 'secret') continue;
+      variables[v.name] = `conformance-${v.name}-shape`;
+    }
+    const ref = `prompt:${template.templateId}@${template.version}`;
+    const res = await driver.post('/v1/prompts:render', { ref, variables });
+    if (res.status !== 200) return;
+    const r = res.json as RenderResponse;
+
+    expect(
+      /^sha256:[0-9a-f]{64}$/.test(r.hash),
+      driver.describe(
+        'schemas/run-event-payloads.schema.json §promptComposed.hash',
+        'hash MUST match `^sha256:[0-9a-f]{64}$`',
+      ),
+    ).toBe(true);
+    for (const [name, h] of Object.entries(r.variableHashes)) {
+      expect(
+        /^sha256:[0-9a-f]{64}$/.test(h),
+        `variableHashes[${name}] MUST match sha256:<hex64>; got ${h}`,
+      ).toBe(true);
+    }
+  });
+
+  it('renders few-shot + schema-hint kinds with non-empty `composed` body', async () => {
+    // RFC 0028 §A says `composed` is the full body regardless of kind.
+    // Regression pin for the rendering-bug fix: few-shot and
+    // schema-hint templates SHOULD surface a body, not the empty
+    // string (which the kind-specific systemPrompt/userPrompt fields
+    // would yield by themselves for these kinds).
+    const d = await readDiscovery();
+    if (!behaviorGate('prompts-endpoints', endpointsSupported(d))) return;
+    const list = await driver.get('/v1/prompts?source=host&limit=200');
+    if (list.status !== 200) return;
+    const body = list.json as ListResponse;
+    const nonSystemUser = body.items.find(
+      (t) => t.kind === 'few-shot' || t.kind === 'schema-hint',
+    );
+    if (!nonSystemUser) return; // host doesn't ship one — soft-skip
+
+    const variables: Record<string, unknown> = {};
+    for (const v of nonSystemUser.variables ?? []) {
+      if (v.source === 'secret') continue;
+      variables[v.name] = 'conformance-value';
+    }
+    const ref = `prompt:${nonSystemUser.templateId}@${nonSystemUser.version}`;
+    const res = await driver.post('/v1/prompts:render', { ref, variables });
+    if (res.status !== 200) return;
+    const r = res.json as RenderResponse;
+    expect(
+      typeof r.composed === 'string' && r.composed.length > 0,
+      driver.describe(
+        'spec/v1/prompts.md §Discovery & distribution',
+        '`composed` body MUST populate for every PromptKind under observability: full',
+      ),
+    ).toBe(true);
+  });
+});

package/src/scenarios/prompt-resolution-chain-agent-intrinsic.test.ts

@@ -0,0 +1,140 @@
+/**
+ * prompt-resolution-chain-agent-intrinsic — RFC 0029 §A layer-2
+ * agent-intrinsic precedence.
+ *
+ * Asserts: when a workflow node has no layer-1 systemPromptRef but is
+ * bound to an agent whose `AgentManifest.systemPromptRef` (or
+ * `systemPrompt`) is set, the agent's intrinsic prompt wins. The
+ * emitted `agent.promptResolved.chain` MUST show
+ * `layer: "agent-intrinsic"` with `applied: true`, and `resolved` MUST
+ * be a synthetic PromptRef projected from the manifest's intrinsic
+ * surface.
+ *
+ * Capability-gated: skips when the host doesn't advertise BOTH
+ * `capabilities.prompts.supported: true` AND
+ * `capabilities.prompts.agentBindings: true`.
+ *
+ * HTTP-driven: skips when no `OPENWOP_BASE_URL` is configured.
+ *
+ *
+ * Under `OPENWOP_REQUIRE_BEHAVIOR=true` the capability gate hardens
+ * from SKIP to FAIL — a host that advertises the gating capability
+ * but doesn't emit the asserted contract fails the scenario instead
+ * of silently skipping. See `conformance/coverage.md` §"Capability-
+ * gated scenarios."
+ *
+ * @see spec/v1/prompts.md §"Resolution chain (normative)" — Layer 2
+ * @see RFCS/0029-prompt-override-hierarchy.md §A
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+
+interface DiscoveryDoc {
+  capabilities?: {
+    prompts?: {
+      supported?: unknown;
+      agentBindings?: unknown;
+    };
+  };
+}
+
+interface AgentPromptResolvedPayload {
+  nodeId: string;
+  kind: string;
+  agentId?: string;
+  chain: Array<{
+    layer: string;
+    source?: string;
+    applied: boolean;
+    reason?: string;
+  }>;
+  resolved: string | null;
+}
+
+async function readDiscovery(): Promise<DiscoveryDoc | null> {
+  const res = await driver.get('/.well-known/openwop');
+  if (res.status !== 200) return null;
+  return res.json as DiscoveryDoc;
+}
+
+function promptsAgentBindings(d: DiscoveryDoc | null): boolean {
+  const p = d?.capabilities?.prompts;
+  if (!p) return false;
+  return p.supported === true && p.agentBindings === true;
+}
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+describe.skipIf(HTTP_SKIP)('prompt-resolution-chain-agent-intrinsic: layer-2 agent intrinsic wins when node has no override (RFC 0029 §A)', () => {
+  it('agent intrinsic systemPromptRef wins over workflow defaults + host defaults when node has no layer-1 ref', async () => {
+    const d = await readDiscovery();
+    if (!behaviorGate('prompts-agent-bindings', promptsAgentBindings(d))) return;
+
+    const res = await driver.post('/v1/host/sample/prompt/resolve', {
+      kind: 'system',
+      node: {
+        nodeId: 'writer',
+        config: {
+          // Layer 1 absent — no systemPromptRef on node.
+          agentId: 'vendor.acme.writer-agent',
+        },
+      },
+      agentManifest: {
+        agentId: 'vendor.acme.writer-agent',
+        // Layer 2 intrinsic — should win.
+        systemPromptRef: 'prompts/intrinsic.md',
+        // Layer 2 overrides also set — for `system` kind, intrinsic
+        // takes precedence over overrides per RFC 0029 §A.
+        promptOverrides: {
+          system: 'prompt:editorial-house-style@1.0.0',
+        },
+      },
+      workflowDefaults: {
+        promptRefs: {
+          system: 'prompt:workflow-default@1.0.0',
+        },
+      },
+      hostDefaults: {
+        system: 'prompt:host-default@1.0.0',
+      },
+    });
+    if (res.status === 404) return;
+    expect(res.status).toBe(200);
+
+    const payload = res.json as AgentPromptResolvedPayload;
+
+    const appliedEntries = payload.chain.filter((c) => c.applied);
+    expect(
+      appliedEntries.length,
+      driver.describe(
+        'spec/v1/prompts.md §Resolution chain (normative)',
+        'exactly one chain entry MUST carry applied: true',
+      ),
+    ).toBe(1);
+    expect(
+      appliedEntries[0]?.layer,
+      driver.describe(
+        'spec/v1/prompts.md §Resolution chain (normative) — Layer 2',
+        'system-kind resolution MUST prefer agent intrinsic (systemPromptRef) over agent-overrides when both are set',
+      ),
+    ).toBe('agent-intrinsic');
+
+    expect(
+      payload.resolved,
+      driver.describe(
+        'spec/v1/prompts.md §Resolution chain (normative) — Layer 2',
+        'resolved MUST mirror the winning chain entry source',
+      ),
+    ).toBe(appliedEntries[0]?.source ?? null);
+
+    expect(
+      payload.agentId,
+      driver.describe(
+        'spec/v1/prompts.md §Resolution chain (normative)',
+        'agent.promptResolved.agentId MUST be set when config.agentId resolves to a known agent',
+      ),
+    ).toBe('vendor.acme.writer-agent');
+  });
+});