fuli-context 0.2.0

package/src/workspace-protocol/manifest-contract.js

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+
+import { rejectDuplicateValues } from './array-validation.js';
+import { createCanonicalBase64UrlSchema } from './base64url-contract.js';
+import {
+  ProviderCapability,
+  WORKSPACE_PROTOCOL_VERSION,
+  WorkspaceRole,
+  WorkspaceVisibility,
+} from './constants.js';
+import {
+  idSchema,
+  revisionSchema,
+  timestampSchema,
+} from './scalar-contract.js';
+import {
+  createPreservedContentTextSchema,
+  createPreservedSemanticTextSchema,
+} from './text-contract.js';
+import { parseProtocolValue } from './validation.js';
+
+const providerIdentifierSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{1,62}$/);
+const MAX_HTTPS_URL_LENGTH = 2_048;
+const ROLELESS_CAPABILITIES = new Set([
+  ProviderCapability.QUERY,
+  ProviderCapability.SYNC,
+]);
+
+function hasSafeHttpsPath(url) {
+  if (/%25/iu.test(url.pathname)) {
+    return false;
+  }
+
+  let decodedPathname;
+
+  try {
+    decodedPathname = decodeURIComponent(url.pathname);
+  } catch {
+    return false;
+  }
+
+  return !/\p{C}/u.test(decodedPathname);
+}
+
+const httpsUrlSchema = z
+  .string()
+  .min(1)
+  .max(MAX_HTTPS_URL_LENGTH)
+  .transform((value, context) => {
+    if (
+      !value.startsWith('https://')
+      || /(?:\s|\p{C})/u.test(value)
+      || value.includes('?')
+      || value.includes('#')
+      || /%(?![0-9A-Fa-f]{2})/u.test(value)
+    ) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Expected a canonical HTTPS URL without whitespace, query, or fragment',
+      });
+      return z.NEVER;
+    }
+
+    let url;
+
+    try {
+      url = new URL(value);
+    } catch {
+      context.addIssue({
+        code: 'custom',
+        message: 'Expected a valid HTTPS URL without credentials',
+      });
+      return z.NEVER;
+    }
+
+    if (
+      url.username !== ''
+      || url.password !== ''
+      || !hasSafeHttpsPath(url)
+    ) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Expected a valid HTTPS URL without credentials',
+      });
+      return z.NEVER;
+    }
+
+    const canonicalUrl = url.href;
+
+    if (canonicalUrl.length > MAX_HTTPS_URL_LENGTH) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Canonical HTTPS URL exceeds the maximum length',
+      });
+      return z.NEVER;
+    }
+
+    return canonicalUrl;
+  });
+
+const protocolVersionsSchema = z
+  .array(z.literal(WORKSPACE_PROTOCOL_VERSION))
+  .min(1)
+  .max(4)
+  .superRefine(rejectDuplicateValues);
+
+const capabilitiesSchema = z
+  .array(z.enum(Object.values(ProviderCapability)))
+  .min(1)
+  .max(8)
+  .superRefine(rejectDuplicateValues);
+
+const signingKeySchema = z.strictObject({
+  keyId: idSchema,
+  algorithm: z.literal('EdDSA'),
+  publicJwk: z.strictObject({
+    kty: z.literal('OKP'),
+    crv: z.literal('Ed25519'),
+    x: createCanonicalBase64UrlSchema(32),
+  }),
+});
+
+const signingKeysSchema = z
+  .array(signingKeySchema)
+  .max(8)
+  .superRefine((keys, context) => {
+    rejectDuplicateValues(
+      keys.map(({ keyId }) => keyId),
+      context,
+      (index) => [index, 'keyId'],
+    );
+  });
+
+export const providerManifestSchema = z.strictObject({
+  providerId: providerIdentifierSchema,
+  displayName: createPreservedSemanticTextSchema(100),
+  protocolVersions: protocolVersionsSchema,
+  apiBaseUrl: httpsUrlSchema,
+  webBaseUrl: httpsUrlSchema,
+  oidc: z.strictObject({
+    issuer: httpsUrlSchema,
+    audience: createPreservedSemanticTextSchema(200),
+  }),
+  capabilities: capabilitiesSchema,
+  signingKeys: signingKeysSchema,
+});
+
+export const workspaceDescriptorSchema = z
+  .strictObject({
+    id: idSchema,
+    slug: providerIdentifierSchema,
+    name: createPreservedSemanticTextSchema(120),
+    description: createPreservedContentTextSchema(1_000).nullable(),
+    visibility: z.enum(Object.values(WorkspaceVisibility)),
+    role: z.enum(Object.values(WorkspaceRole)).nullable(),
+    capabilities: capabilitiesSchema,
+    revision: revisionSchema,
+    updatedAt: timestampSchema,
+  })
+  .superRefine((workspace, context) => {
+    if (workspace.role !== null) {
+      return;
+    }
+
+    workspace.capabilities.forEach((capability, index) => {
+      if (!ROLELESS_CAPABILITIES.has(capability)) {
+        context.addIssue({
+          code: 'custom',
+          path: ['capabilities', index],
+          message: 'A roleless workspace cannot expose member capabilities',
+        });
+      }
+    });
+  });
+
+export function parseProviderManifest(value) {
+  return parseProtocolValue(providerManifestSchema, value, 'Provider Manifest');
+}
+
+export function parseWorkspaceDescriptor(value) {
+  return parseProtocolValue(
+    workspaceDescriptorSchema,
+    value,
+    'Workspace descriptor',
+  );
+}

package/src/workspace-protocol/publication-contract.js

@@ -0,0 +1,212 @@
+import { Buffer } from 'node:buffer';
+
+import { z } from 'zod';
+
+import { canonicalJson } from '../publication/canonical-json.js';
+import { rejectDuplicateValues } from './array-validation.js';
+import { createCanonicalBase64UrlSchema } from './base64url-contract.js';
+import {
+  ProposalStatus,
+  WORKSPACE_PROTOCOL_VERSION,
+} from './constants.js';
+import { sourceReferenceSchema } from './fact-contract.js';
+import { refineUtf8JsonByteBudget } from './json-budget.js';
+import {
+  idSchema,
+  revisionSchema,
+  sourceUriSchema,
+} from './scalar-contract.js';
+import {
+  createPreservedContentTextSchema,
+  createPreservedSemanticTextSchema,
+} from './text-contract.js';
+import { parseProtocolValue } from './validation.js';
+
+const MAX_PUBLICATION_PROPOSAL_BYTES = 1_048_576;
+const PROJECTED_ZERO_SIGNATURE = Buffer.alloc(64).toString('base64url');
+const changeOperationSchema = z.enum([
+  'add',
+  'supplement',
+  'replace',
+  'retract',
+  'restore',
+]);
+const publicationSourceSchema = sourceReferenceSchema.extend({
+  uri: sourceUriSchema,
+});
+
+const publicationChangeSchema = z
+  .strictObject({
+    clientFactId: idSchema,
+    subject: createPreservedSemanticTextSchema(500),
+    predicate: createPreservedSemanticTextSchema(160),
+    object: createPreservedContentTextSchema(20_000),
+    operation: changeOperationSchema,
+    targetFactIds: z.array(idSchema).max(50),
+  })
+  .superRefine((change, context) => {
+    rejectDuplicateValues(
+      change.targetFactIds,
+      context,
+      (index) => ['targetFactIds', index],
+    );
+
+    if (change.operation === 'add' && change.targetFactIds.length !== 0) {
+      context.addIssue({
+        code: 'custom',
+        path: ['targetFactIds'],
+        message: 'An add change cannot target an existing fact',
+      });
+    }
+
+    if (change.operation !== 'add' && change.targetFactIds.length === 0) {
+      context.addIssue({
+        code: 'custom',
+        path: ['targetFactIds'],
+        message: 'This change operation requires an existing target fact',
+      });
+    }
+  });
+
+const unsignedPublicationProposalShape = {
+  protocolVersion: z.literal(WORKSPACE_PROTOCOL_VERSION),
+  publicationId: idSchema,
+  idempotencyKey: createPreservedSemanticTextSchema(200),
+  workspaceId: idSchema,
+  source: publicationSourceSchema,
+  changes: z.array(publicationChangeSchema).min(1).max(100),
+  policyVersion: createPreservedSemanticTextSchema(32),
+  signingKeyId: idSchema,
+};
+
+function refinePublicationProposal(proposal, context) {
+  const clientFactIdValues = proposal.changes.map(
+    ({ clientFactId }) => clientFactId,
+  );
+  const clientFactIds = new Set(clientFactIdValues);
+
+  rejectDuplicateValues(
+    clientFactIdValues,
+    context,
+    (index) => ['changes', index, 'clientFactId'],
+  );
+
+  const targetedFactIds = new Set();
+
+  proposal.changes.forEach(({ targetFactIds }, changeIndex) => {
+    const changeTargetFactIds = new Set();
+
+    targetFactIds.forEach((targetFactId, targetIndex) => {
+      const path = ['changes', changeIndex, 'targetFactIds', targetIndex];
+
+      if (clientFactIds.has(targetFactId)) {
+        context.addIssue({
+          code: 'custom',
+          path,
+          message: 'An existing target cannot match a proposal client fact ID',
+        });
+      }
+
+      if (targetedFactIds.has(targetFactId)) {
+        context.addIssue({
+          code: 'custom',
+          path,
+          message: 'An existing fact cannot be targeted by multiple changes',
+        });
+      }
+
+      changeTargetFactIds.add(targetFactId);
+    });
+
+    changeTargetFactIds.forEach((targetFactId) => {
+      targetedFactIds.add(targetFactId);
+    });
+  });
+
+  const projectedProposal = 'signature' in proposal
+    ? proposal
+    : { ...proposal, signature: PROJECTED_ZERO_SIGNATURE };
+
+  refineUtf8JsonByteBudget(
+    projectedProposal,
+    context,
+    MAX_PUBLICATION_PROPOSAL_BYTES,
+    'Publication proposal',
+  );
+}
+
+const unsignedPublicationProposalSchema = z
+  .strictObject(unsignedPublicationProposalShape)
+  .superRefine(refinePublicationProposal);
+
+export const publicationProposalSchema = z
+  .strictObject({
+    ...unsignedPublicationProposalShape,
+    signature: createCanonicalBase64UrlSchema(64),
+  })
+  .superRefine(refinePublicationProposal);
+
+export const publicationResultSchema = z
+  .strictObject({
+    proposalId: idSchema,
+    status: z.enum(Object.values(ProposalStatus)),
+    workspaceRevision: revisionSchema.nullable(),
+    reason: createPreservedSemanticTextSchema(500).nullable(),
+  })
+  .superRefine((result, context) => {
+    if (
+      result.status === ProposalStatus.EFFECTIVE
+      && result.workspaceRevision === null
+    ) {
+      context.addIssue({
+        code: 'custom',
+        path: ['workspaceRevision'],
+        message: 'An effective proposal requires a workspace revision',
+      });
+    }
+
+    if (
+      result.status !== ProposalStatus.EFFECTIVE
+      && result.workspaceRevision !== null
+    ) {
+      context.addIssue({
+        code: 'custom',
+        path: ['workspaceRevision'],
+        message: 'A non-effective proposal cannot have a workspace revision',
+      });
+    }
+
+    if (result.status === ProposalStatus.REJECTED && result.reason === null) {
+      context.addIssue({
+        code: 'custom',
+        path: ['reason'],
+        message: 'A rejected proposal requires a reason',
+      });
+    }
+  });
+
+export function parsePublicationProposal(value) {
+  return parseProtocolValue(
+    publicationProposalSchema,
+    value,
+    'Publication proposal',
+  );
+}
+
+export function parsePublicationResult(value) {
+  return parseProtocolValue(
+    publicationResultSchema,
+    value,
+    'Publication result',
+  );
+}
+
+export function publicationSigningBytes(value) {
+  const parsed = parseProtocolValue(
+    unsignedPublicationProposalSchema,
+    value,
+    'Unsigned publication proposal',
+  );
+
+  return Buffer.from(canonicalJson(parsed), 'utf8');
+}

package/src/workspace-protocol/query-contract.js

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+
+import { rejectDuplicateValues } from './array-validation.js';
+import { factProjectionSchema } from './fact-contract.js';
+import { refineUtf8JsonByteBudget } from './json-budget.js';
+import {
+  cursorSchema,
+  idSchema,
+  revisionSchema,
+  timestampSchema,
+} from './scalar-contract.js';
+import { createNormalizedSemanticTextSchema } from './text-contract.js';
+import { parseProtocolValue } from './validation.js';
+
+const MAX_CONTEXT_PACK_BYTES = 1_048_576;
+
+const initialWorkspaceQuerySchema = z
+  .strictObject({
+    text: createNormalizedSemanticTextSchema(512).optional(),
+    subjects: z.array(createNormalizedSemanticTextSchema(500)).max(20).default([]),
+    predicates: z.array(createNormalizedSemanticTextSchema(160)).max(20).default([]),
+    factIds: z.array(idSchema).max(50).default([]),
+    asOf: timestampSchema.optional(),
+    includeHistory: z.boolean().default(false),
+    limit: z.number().int().min(1).max(100).default(20),
+    cursor: z.literal(null).default(null),
+  })
+  .superRefine((query, context) => {
+    rejectDuplicateValues(
+      query.subjects,
+      context,
+      (index) => ['subjects', index],
+    );
+    rejectDuplicateValues(
+      query.predicates,
+      context,
+      (index) => ['predicates', index],
+    );
+    rejectDuplicateValues(
+      query.factIds,
+      context,
+      (index) => ['factIds', index],
+    );
+
+    if (
+      query.text === undefined
+      && query.subjects.length === 0
+      && query.predicates.length === 0
+      && query.factIds.length === 0
+    ) {
+      context.addIssue({
+        code: 'custom',
+        message: 'At least one query selector is required',
+      });
+    }
+  });
+
+const continuationWorkspaceQuerySchema = z.strictObject({
+  cursor: cursorSchema,
+});
+
+export const workspaceQuerySchema = z.union([
+  continuationWorkspaceQuerySchema,
+  initialWorkspaceQuerySchema,
+]);
+
+export const contextPackSchema = z
+  .strictObject({
+    workspaceId: idSchema,
+    workspaceRevision: revisionSchema,
+    generatedAt: timestampSchema,
+    freshness: z.strictObject({
+      state: z.enum(['fresh', 'stale']),
+      lastSyncedAt: timestampSchema,
+    }),
+    facts: z.array(factProjectionSchema).max(100),
+    nextCursor: cursorSchema.nullable(),
+    truncated: z.boolean(),
+  })
+  .superRefine((contextPack, context) => {
+    rejectDuplicateValues(
+      contextPack.facts.map(({ id }) => id),
+      context,
+      (index) => ['facts', index, 'id'],
+    );
+
+    const workspaceRevision = BigInt(contextPack.workspaceRevision);
+
+    contextPack.facts.forEach(({ revision }, index) => {
+      if (BigInt(revision) > workspaceRevision) {
+        context.addIssue({
+          code: 'custom',
+          path: ['facts', index, 'revision'],
+          message: 'Fact revision cannot exceed the Context Pack workspace revision',
+        });
+      }
+    });
+
+    if (contextPack.truncated && contextPack.nextCursor === null) {
+      context.addIssue({
+        code: 'custom',
+        path: ['nextCursor'],
+        message: 'A truncated Context Pack requires a next cursor',
+      });
+    }
+
+    if (!contextPack.truncated && contextPack.nextCursor !== null) {
+      context.addIssue({
+        code: 'custom',
+        path: ['nextCursor'],
+        message: 'A complete Context Pack cannot have a next cursor',
+      });
+    }
+
+    const generatedAtEpoch = Date.parse(contextPack.generatedAt);
+
+    contextPack.facts.forEach(({ recordedAt }, index) => {
+      if (Date.parse(recordedAt) > generatedAtEpoch) {
+        context.addIssue({
+          code: 'custom',
+          path: ['facts', index, 'recordedAt'],
+          message: 'Fact recording time cannot follow Context Pack generation',
+        });
+      }
+    });
+
+    if (Date.parse(contextPack.freshness.lastSyncedAt) > generatedAtEpoch) {
+      context.addIssue({
+        code: 'custom',
+        path: ['freshness', 'lastSyncedAt'],
+        message: 'Sync time cannot follow Context Pack generation',
+      });
+    }
+
+    refineUtf8JsonByteBudget(
+      contextPack,
+      context,
+      MAX_CONTEXT_PACK_BYTES,
+      'Context Pack',
+    );
+  });
+
+export function parseWorkspaceQuery(value) {
+  return parseProtocolValue(workspaceQuerySchema, value, 'Workspace query');
+}
+
+export function parseContextPack(value) {
+  return parseProtocolValue(contextPackSchema, value, 'Context Pack');
+}