fuli-context 0.7.4-beta.2 → 0.7.5

package/src/graphiti/provider-client.js

@@ -79,6 +79,269 @@ export class GraphitiProviderClient {
       `/v1/personal-projects/${encodeURIComponent(projectId)}?${query}`
     );
   }
+  upsertProjectAgent(input) {
+    return this.#request('/v1/project-agents', { method: 'PUT', body: input });
+  }
+  listProjectAgents(
+    personalSpaceId,
+    personalProjectId = null,
+    { status = null, capability = null } = {}
+  ) {
+    const query = new URLSearchParams({
+      personal_space_id: personalSpaceId
+    });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    if (status) query.set('status', status);
+    if (capability) query.set('capability', capability);
+    return this.#request(`/v1/project-agents?${query}`);
+  }
+  getProjectAgent(personalSpaceId, personalProjectId, agentId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    return this.#request(
+      `/v1/project-agents/${encodeURIComponent(agentId)}?${query}`
+    );
+  }
+  deleteProjectAgent(personalSpaceId, agentId, reason = 'archived by user') {
+    const query = new URLSearchParams({
+      personal_space_id: personalSpaceId,
+      reason
+    });
+    return this.#request(
+      `/v1/project-agents/${encodeURIComponent(agentId)}?${query}`,
+      { method: 'DELETE' }
+    );
+  }
+  cleanupProjectAgentTestRoles(personalSpaceId, testSource) {
+    const query = new URLSearchParams({
+      personal_space_id: personalSpaceId,
+      test_source: testSource
+    });
+    return this.#request(`/v1/project-agents/test-cleanup?${query}`, {
+      method: 'POST'
+    });
+  }
+  createProjectAgentAssignment(input) {
+    return this.#request('/v1/project-agent-assignments', {
+      method: 'POST', body: input
+    });
+  }
+  listProjectAgentAssignments({
+    personalSpaceId,
+    personalProjectId = null,
+    agentId = null,
+    status = null
+  }) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    if (agentId) query.set('agent_id', agentId);
+    if (status) query.set('status', status);
+    return this.#request(`/v1/project-agent-assignments?${query}`);
+  }
+  endProjectAgentAssignment(input) {
+    return this.#request('/v1/project-agent-assignments/end', {
+      method: 'POST', body: input
+    });
+  }
+  replaceProjectAgentAssignment(input) {
+    return this.#request('/v1/project-agent-assignments/replace', {
+      method: 'POST', body: input
+    });
+  }
+  submitProjectAgentTask(input) {
+    return this.#request('/v1/project-agent-tasks', {
+      method: 'POST', body: input
+    });
+  }
+  listProjectAgentTasks({
+    personalSpaceId,
+    personalProjectId = null,
+    agentId = null,
+    status = null,
+    limit = null
+  }) {
+    const query = new URLSearchParams({
+      personal_space_id: personalSpaceId
+    });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    if (agentId) query.set('agent_id', agentId);
+    if (status) query.set('status', status);
+    if (limit !== null && limit !== undefined) query.set('limit', String(limit));
+    return this.#request(`/v1/project-agent-tasks?${query}`);
+  }
+  viewProjectAgentTask(personalSpaceId, taskId, { includeEvents = true } = {}) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    query.set('include_events', String(includeEvents));
+    return this.#request(
+      `/v1/project-agent-tasks/${encodeURIComponent(taskId)}?${query}`
+    );
+  }
+  recordProjectAgentTaskActivity(input) {
+    return this.#request(
+      `/v1/project-agent-tasks/${encodeURIComponent(input.task_id ?? input.taskId)}/events`,
+      {
+        method: 'POST', body: input
+      }
+    );
+  }
+  listProjectAgentActivity({
+    personalSpaceId,
+    agentId,
+    fromDate = null,
+    toDate = null
+  }) {
+    const today = new Date().toISOString().slice(0, 10);
+    const query = new URLSearchParams({
+      personal_space_id: personalSpaceId,
+      from: fromDate ?? toDate ?? today,
+      to: toDate ?? fromDate ?? today
+    });
+    return this.#request(
+      `/v1/project-agents/${encodeURIComponent(agentId)}/activity?${query}`
+    );
+  }
+  getProjectAgentRecruitmentPolicy(personalSpaceId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(`/v1/project-agent-recruitment-policy?${query}`);
+  }
+  updateProjectAgentRecruitmentPolicy(input) {
+    return this.#request('/v1/project-agent-recruitment-policy', {
+      method: 'PUT', body: input
+    });
+  }
+  listProjectAgentRecruitments({
+    personalSpaceId,
+    personalProjectId = null,
+    taskId = null,
+    status = null
+  }) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    if (taskId) query.set('task_id', taskId);
+    if (status) query.set('status', status);
+    return this.#request(`/v1/project-agent-recruitments?${query}`);
+  }
+  decideProjectAgentRecruitment(input) {
+    return this.#request(
+      `/v1/project-agent-recruitments/${encodeURIComponent(
+        input.recruitment_id ?? input.recruitmentId
+      )}/decision`,
+      { method: 'POST', body: input }
+    );
+  }
+  upsertExecutor(input) {
+    return this.#request('/v1/executors', { method: 'PUT', body: input });
+  }
+  listExecutors(
+    personalSpaceId,
+    { capability = null, availableOnly = false } = {}
+  ) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    if (capability) query.set('capability', capability);
+    if (availableOnly) query.set('available_only', 'true');
+    return this.#request(`/v1/executors?${query}`);
+  }
+  getExecutor(personalSpaceId, executorId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(`/v1/executors/${encodeURIComponent(executorId)}?${query}`);
+  }
+  deleteExecutor(personalSpaceId, executorId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(`/v1/executors/${encodeURIComponent(executorId)}?${query}`, {
+      method: 'DELETE'
+    });
+  }
+  preflightExecutor(input) {
+    return this.#request('/v1/executors/preflight', { method: 'POST', body: input });
+  }
+  authorizeExecutor(input) {
+    return this.#request('/v1/executors/authorization', {
+      method: 'POST', body: input
+    });
+  }
+  reportExecutorHealth(input) {
+    return this.#request('/v1/executors/health', {
+      method: 'POST', body: input
+    });
+  }
+  recordProjectAgentExecutorActual(input) {
+    return this.#request('/v1/project-agent-executor-actuals', {
+      method: 'POST', body: input
+    });
+  }
+  upsertExecutorRoutingRule(input) {
+    return this.#request('/v1/executor-routing-rules', {
+      method: 'PUT', body: input
+    });
+  }
+  updateExecutorRoutingRule(input) {
+    return this.#request(
+      `/v1/executor-routing-rules/${encodeURIComponent(
+        input.rule_id ?? input.ruleId
+      )}`,
+      { method: 'PATCH', body: input }
+    );
+  }
+  listExecutorRoutingRules({
+    personalSpaceId,
+    scope = null,
+    personalProjectId = null,
+    taskId = null,
+    status = null,
+    enabled = null
+  }) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    if (scope) query.set('scope', scope);
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    if (taskId) query.set('task_id', taskId);
+    if (status) query.set('status', status);
+    else if (enabled !== null && enabled !== undefined) {
+      query.set('status', enabled ? 'active' : 'disabled');
+    }
+    return this.#request(`/v1/executor-routing-rules?${query}`);
+  }
+  getExecutorRoutingRule(personalSpaceId, ruleId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(
+      `/v1/executor-routing-rules/${encodeURIComponent(ruleId)}?${query}`
+    );
+  }
+  deleteExecutorRoutingRule(personalSpaceId, ruleId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(
+      `/v1/executor-routing-rules/${encodeURIComponent(ruleId)}?${query}`,
+      { method: 'DELETE' }
+    );
+  }
+  recordProjectAgentTaskOutcome(input) {
+    return this.#request('/v1/project-agent-routing-outcomes', {
+      method: 'POST', body: input
+    });
+  }
+  listProjectAgentRoutingLearning({
+    personalSpaceId,
+    personalProjectId = null,
+    workKind = null,
+    agentId = null,
+    executorId = null
+  }) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    if (workKind) query.set('work_kind', workKind);
+    if (agentId) query.set('agent_id', agentId);
+    if (executorId) query.set('executor_id', executorId);
+    return this.#request(`/v1/project-agent-routing-learning?${query}`);
+  }
+  ignoreProjectAgentRoutingLearning(input) {
+    return this.#request('/v1/project-agent-routing-learning/ignore', {
+      method: 'POST', body: input
+    });
+  }
+  resetProjectAgentRoutingLearning(input) {
+    return this.#request('/v1/project-agent-routing-learning/reset', {
+      method: 'POST', body: input
+    });
+  }
   createPublicationDraft(input) {
     return this.#request('/v1/publication-drafts', { method: 'POST', body: input });
   }
@@ -320,12 +583,18 @@ export class GraphitiProviderClient {
     );
   }
   search(input) { return this.#request('/v1/search', { method: 'POST', body: input }); }
-  collaborationPreferences(personalSpaceId, personalProjectId = null, limit = 100) {
+  collaborationPreferences(
+    personalSpaceId,
+    personalProjectId = null,
+    limit = 100,
+    projectAgentId = null
+  ) {
     const query = new URLSearchParams({
       personal_space_id: personalSpaceId,
       limit: String(limit)
     });
     if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    if (projectAgentId) query.set('project_agent_id', projectAgentId);
     return this.#request(`/v1/collaboration-preferences?${query}`);
   }
   graph(spaceId, limit = 500, personalProjectId = null, offset = null) {

package/src/graphiti/runtime-config.js

@@ -38,7 +38,12 @@ function validateConfig(config) {
   if (!config.personal.spaceId) fail('personal.spaceId is required');
   if (!Array.isArray(config.workspaces)) fail('workspaces must be an array');
   for (const [index, workspace] of config.workspaces.entries()) {
-    provider(workspace, `workspaces[${index}]`);
+    const label = `workspaces[${index}]`;
+    provider(workspace, label);
+    if (workspace.protocol !== undefined &&
+        !['graphiti-v1', 'fuli-workspace-v1'].includes(workspace.protocol)) {
+      fail(`${label}.protocol is unsupported`);
+    }
   }
 }
 

package/src/graphiti/workspace-provider-client.js

@@ -0,0 +1,403 @@
+import { createHash } from 'node:crypto';
+
+import {
+  GraphitiProviderClient,
+  ProviderRequestError
+} from './provider-client.js';
+import { canonicalProviderUrl } from './runtime-config.js';
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const MAX_REQUEST_TIMEOUT_MS = 2_147_483_647;
+const MAX_LIST_PAGES = 100;
+const FULI_WORKSPACE_PROTOCOL = 'fuli-workspace-v1';
+const GRAPHITI_PROTOCOL = 'graphiti-v1';
+
+const GRAPHITI_CAPABILITIES = Object.freeze({
+  browsePublicProjects: true,
+  publishProject: true,
+  submitKnowledge: true,
+  subscribeProject: true,
+  reviewProposals: true,
+  query: true
+});
+
+export const FULI_WORKSPACE_CAPABILITIES = Object.freeze({
+  browsePublicProjects: true,
+  publishProject: false,
+  submitKnowledge: false,
+  subscribeProject: true,
+  reviewProposals: false,
+  query: true
+});
+
+export function createWorkspaceProvider(workspace, {
+  fetchImpl = globalThis.fetch,
+  requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS
+} = {}) {
+  const providerUrl = canonicalProviderUrl(workspace.providerUrl);
+  const protocol = workspace.protocol ?? GRAPHITI_PROTOCOL;
+  const fuliWorkspace = protocol === FULI_WORKSPACE_PROTOCOL;
+  const client = fuliWorkspace
+    ? new FuliWorkspaceProviderClient({
+      baseUrl: providerUrl,
+      accessToken: workspace.accessToken,
+      fetchImpl,
+      requestTimeoutMs
+    })
+    : new GraphitiProviderClient({
+      baseUrl: providerUrl,
+      accessToken: workspace.accessToken,
+      fetchImpl,
+      requestTimeoutMs
+    });
+  return {
+    ...workspace,
+    providerUrl,
+    protocol,
+    capabilities: fuliWorkspace ? FULI_WORKSPACE_CAPABILITIES : GRAPHITI_CAPABILITIES,
+    client
+  };
+}
+
+export function aggregatePublicCapabilities(workspaces, providerStatuses, projects) {
+  const ready = new Set(providerStatuses
+    .filter(({ status }) => status === 'ready')
+    .map(({ providerUrl }) => providerUrl));
+  const supports = (capability) => [...workspaces.values()].some((workspace) =>
+    ready.has(workspace.providerUrl) && workspace.capabilities[capability] === true
+  );
+  return {
+    browsePublicProjects: supports('browsePublicProjects'),
+    publishProject: supports('publishProject'),
+    submitKnowledge: supports('submitKnowledge'),
+    subscribeProject: supports('subscribeProject'),
+    reviewProposals: supports('reviewProposals') &&
+      projects.some(({ role }) => role === 'maintainer')
+  };
+}
+
+export class FuliWorkspaceProviderClient {
+  #accessToken;
+  #fetch;
+
+  constructor({
+    baseUrl,
+    accessToken,
+    fetchImpl = globalThis.fetch,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS
+  }) {
+    if (!baseUrl) throw new TypeError('Fuli Workspace provider baseUrl is required');
+    if (!accessToken) throw new TypeError('Fuli Workspace provider accessToken is required');
+    if (typeof fetchImpl !== 'function') throw new TypeError('fetch implementation is required');
+    if (!Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 1 ||
+        requestTimeoutMs > MAX_REQUEST_TIMEOUT_MS) {
+      throw new TypeError('Fuli Workspace provider timeout must be a positive safe integer');
+    }
+    this.baseUrl = canonicalProviderUrl(baseUrl);
+    this.#accessToken = accessToken;
+    this.#fetch = fetchImpl;
+    this.requestTimeoutMs = requestTimeoutMs;
+  }
+
+  async health() {
+    const [payload, session] = await Promise.all([
+      this.#request('/healthz', { authenticated: false }),
+      this.#request('/v1/auth/session')
+    ]);
+    if (payload?.status !== 'ok' || String(payload?.protocolVersion) !== '1') {
+      throw invalidResponse('Fuli Workspace health response is incompatible');
+    }
+    if (session?.authenticated !== true) {
+      throw invalidResponse('Fuli Workspace authentication session is invalid');
+    }
+    return {
+      status: 'ready',
+      providerId: 'fuli-workspace',
+      mode: 'workspace',
+      storage: 'sqlite',
+      protocol: FULI_WORKSPACE_PROTOCOL,
+      protocolVersion: '1'
+    };
+  }
+
+  async listSpaces() {
+    const workspaces = [];
+    let cursor = null;
+    for (let page = 0; page < MAX_LIST_PAGES; page += 1) {
+      const query = new URLSearchParams({ limit: '500' });
+      if (cursor !== null) query.set('cursor', cursor);
+      const payload = await this.#request(`/v1/workspaces?${query}`);
+      if (!Array.isArray(payload?.workspaces)) {
+        throw invalidResponse('Fuli Workspace returned an invalid workspace list');
+      }
+      workspaces.push(...payload.workspaces.map(workspaceSpace));
+      if (payload.hasMore !== true) return workspaces;
+      const nextCursor = nonEmptyString(payload.nextCursor);
+      if (!nextCursor || nextCursor === cursor) {
+        throw invalidResponse('Fuli Workspace returned an invalid list cursor');
+      }
+      cursor = nextCursor;
+    }
+    throw invalidResponse('Fuli Workspace workspace listing exceeded the page limit');
+  }
+
+  async search(input) {
+    const spaceIds = uniqueStrings(input?.space_ids);
+    const text = nonEmptyString(input?.query);
+    if (!spaceIds.length) return { facts: [], entities: [] };
+    if (!text || text.length > 512) {
+      throw new TypeError('Fuli Workspace search query must contain 1 to 512 characters');
+    }
+    const limit = boundedInteger(input?.limit, 20, 1, 100);
+    const pages = await Promise.all(spaceIds.map(async (spaceId) => {
+      const payload = await this.#request(
+        `/v1/workspaces/${encodeURIComponent(spaceId)}/query`,
+        {
+          method: 'POST',
+          body: {
+            text,
+            includeHistory: input?.include_historical === true,
+            limit
+          }
+        }
+      );
+      if (!Array.isArray(payload?.facts)) {
+        throw invalidResponse('Fuli Workspace returned an invalid query result');
+      }
+      return payload.facts.map((fact) => searchFact(fact, spaceId));
+    }));
+    return { facts: pages.flat(), entities: [] };
+  }
+
+  async graph(spaceId, limit = 500, personalProjectId = null, offset = null) {
+    if (personalProjectId !== null) {
+      throw new TypeError('Fuli Workspace graphs do not support personal project scope');
+    }
+    const safeSpaceId = nonEmptyString(spaceId);
+    if (!safeSpaceId) throw new TypeError('Fuli Workspace ID is required');
+    const pageLimit = boundedInteger(limit, 500, 1, 500);
+    const pageOffset = offset === null
+      ? 0
+      : boundedInteger(offset, 0, 0, Number.MAX_SAFE_INTEGER);
+    const payload = await this.#request(
+      `/v1/workspaces/${encodeURIComponent(safeSpaceId)}/snapshot`
+    );
+    if (!Array.isArray(payload?.facts)) {
+      throw invalidResponse('Fuli Workspace returned an invalid snapshot');
+    }
+    const selected = payload.facts.slice(pageOffset, pageOffset + pageLimit);
+    const graph = factsGraph(selected, safeSpaceId);
+    const truncated = pageOffset + selected.length < payload.facts.length;
+    return {
+      space_id: safeSpaceId,
+      ...graph,
+      truncated,
+      next_offset: truncated ? pageOffset + selected.length : null
+    };
+  }
+
+  createSpace() { return unsupported(); }
+  listProjectReleases() { return unsupported(); }
+  deleteProject() { return unsupported(); }
+  createProjectRelation() { return unsupported(); }
+  listProjectRelations() { return unsupported(); }
+  decideProjectRelation() { return unsupported(); }
+  createProposal() { return unsupported(); }
+  listProposals() { return unsupported(); }
+  decideProposal() { return unsupported(); }
+
+  async #request(path, { method = 'GET', body, authenticated = true } = {}) {
+    const url = new URL(path, `${this.baseUrl}/`);
+    if (url.origin !== this.baseUrl || !url.pathname.startsWith('/')) {
+      throw new TypeError('Fuli Workspace request escaped the configured provider origin');
+    }
+    const headers = { accept: 'application/json' };
+    if (authenticated) headers.authorization = `Bearer ${this.#accessToken}`;
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, this.requestTimeoutMs);
+    try {
+      const response = await this.#fetch(url, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: 'error',
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new ProviderRequestError(
+          `Fuli Workspace provider returned HTTP ${response.status}.`,
+          {
+            status: response.status,
+            code: response.status >= 500 ? 'provider_http_5xx' : 'provider_error'
+          }
+        );
+      }
+      return await safeJson(response);
+    } catch (error) {
+      if (error instanceof ProviderRequestError) throw error;
+      throw new ProviderRequestError(
+        timedOut
+          ? 'Fuli Workspace provider request timed out.'
+          : 'Fuli Workspace provider is unavailable.',
+        {
+          status: timedOut ? 504 : 0,
+          code: timedOut ? 'provider_timeout' : 'provider_unavailable'
+        }
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+function workspaceSpace(workspace) {
+  const id = nonEmptyString(workspace?.id);
+  const name = nonEmptyString(workspace?.name);
+  if (!id || !name) throw invalidResponse('Fuli Workspace returned an invalid workspace');
+  return {
+    id,
+    name,
+    kind: 'project',
+    description: typeof workspace.description === 'string' ? workspace.description : null,
+    visibility: workspace.visibility ?? null,
+    status: workspace.status ?? null,
+    current_revision: workspace.revision ?? null,
+    created_at: workspace.createdAt ?? null,
+    updated_at: workspace.updatedAt ?? null,
+    owner_id: null
+  };
+}
+
+function searchFact(fact, spaceId) {
+  const triple = factTriple(fact);
+  return {
+    id: triple.id,
+    fact: `${triple.subject} ${triple.predicate} ${triple.object}`,
+    source_entity: triple.subject,
+    target_entity: triple.object,
+    relationship: triple.predicate,
+    space_id: spaceId,
+    defined_project_id: spaceId,
+    scope_distance: 0,
+    score: 1,
+    origin_quadrant: fact.originQuadrant ?? 'known_known',
+    confirmation_status: fact.confirmationStatus ?? 'confirmed',
+    valid_at: fact.validFrom ?? fact.createdAt ?? null,
+    invalid_at: fact.validTo ?? null,
+    created_at: fact.createdAt ?? null
+  };
+}
+
+function factsGraph(facts, spaceId) {
+  const nodes = new Map();
+  const edges = facts.map((fact) => {
+    const triple = factTriple(fact);
+    const source = entityNode(spaceId, triple.subject, fact);
+    const target = entityNode(spaceId, triple.object, fact);
+    nodes.set(source.id, source);
+    nodes.set(target.id, target);
+    return {
+      id: triple.id,
+      source: source.id,
+      target: target.id,
+      source_name: triple.subject,
+      target_name: triple.object,
+      type: triple.predicate,
+      fact: `${triple.subject} ${triple.predicate} ${triple.object}`,
+      origin_quadrant: fact.originQuadrant ?? 'known_known',
+      current_quadrant: fact.originQuadrant ?? 'known_known',
+      epistemic_status: 'confirmed',
+      epistemic_state_explicit: true,
+      confirmation_status: fact.confirmationStatus ?? 'confirmed',
+      confirmation_state_explicit: true,
+      profile_aspect: null,
+      valid_at: fact.validFrom ?? fact.createdAt ?? null,
+      invalid_at: fact.validTo ?? null,
+      created_at: fact.createdAt ?? null,
+      attributes: {
+        workspaceId: spaceId,
+        revision: fact.revision ?? null,
+        confirmedBy: fact.confirmedBy ?? null,
+        sources: Array.isArray(fact.sources) ? fact.sources : []
+      },
+      evidence: Array.isArray(fact.evidence) ? fact.evidence : []
+    };
+  });
+  return { nodes: [...nodes.values()], edges };
+}
+
+function entityNode(spaceId, name, fact) {
+  return {
+    id: `workspace-entity:${stableId(spaceId, name)}`,
+    name,
+    type: 'WorkspaceEntity',
+    group_id: spaceId,
+    summary: 'Entity referenced by a confirmed shared workspace fact.',
+    origin_quadrant: fact.originQuadrant ?? 'known_known',
+    current_quadrant: fact.originQuadrant ?? 'known_known',
+    epistemic_status: 'confirmed',
+    epistemic_state_explicit: true,
+    confirmation_status: fact.confirmationStatus ?? 'confirmed',
+    confirmation_state_explicit: true,
+    profile_aspect: null,
+    created_at: fact.createdAt ?? null,
+    invalid_at: null
+  };
+}
+
+function factTriple(fact) {
+  const id = nonEmptyString(fact?.id);
+  const subject = nonEmptyString(fact?.subject);
+  const predicate = nonEmptyString(fact?.predicate);
+  const object = nonEmptyString(fact?.object);
+  if (!id || !subject || !predicate || !object) {
+    throw invalidResponse('Fuli Workspace returned an invalid fact');
+  }
+  return { id, subject, predicate, object };
+}
+
+function stableId(spaceId, value) {
+  return createHash('sha256').update(`${spaceId}\0${value}`, 'utf8').digest('hex').slice(0, 24);
+}
+
+function uniqueStrings(values) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map(nonEmptyString).filter(Boolean))];
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function boundedInteger(value, fallback, minimum, maximum) {
+  if (value === undefined || value === null) return fallback;
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new TypeError('Fuli Workspace pagination value is invalid');
+  }
+  return value;
+}
+
+async function safeJson(response) {
+  const type = response.headers.get('content-type') ?? '';
+  if (!type.includes('application/json')) {
+    throw invalidResponse('Fuli Workspace returned a non-JSON response');
+  }
+  try {
+    return await response.json();
+  } catch {
+    throw invalidResponse('Fuli Workspace returned invalid JSON');
+  }
+}
+
+function invalidResponse(message) {
+  return new ProviderRequestError(message, { code: 'provider_invalid_response' });
+}
+
+function unsupported() {
+  throw new TypeError('Operation is not supported by fuli-workspace-v1');
+}