fuli-context 0.2.0

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

@@ -0,0 +1,192 @@
+import { z } from 'zod';
+
+const MAX_SOURCE_URI_LENGTH = 2_048;
+const HTTP_SOURCE_URI_SCHEMES = new Set(['https', 'http']);
+const CUSTOM_SOURCE_URI_SCHEMES = new Set([
+  'prd',
+  'git',
+  'github',
+  'gitlab',
+  'jira',
+  'linear',
+  'notion',
+]);
+const ALLOWED_SOURCE_URI_SCHEMES = new Set([
+  ...HTTP_SOURCE_URI_SCHEMES,
+  ...CUSTOM_SOURCE_URI_SCHEMES,
+]);
+
+function parseRawHierarchicalUri(value) {
+  const match = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/]+)(\/.*)?$/u.exec(value);
+
+  if (match === null) {
+    return null;
+  }
+
+  return {
+    scheme: match[1].toLowerCase(),
+    authority: match[2],
+    path: match[3] ?? '',
+  };
+}
+
+function isUnsafeRawSourceUri(value, { authority }) {
+  return (
+    /\p{C}/u.test(value)
+    || /\s/u.test(value)
+    || value.includes('\\')
+    || value.includes('?')
+    || value.includes('#')
+    || authority.includes('@')
+  );
+}
+
+function isSafeCustomSourceUri({ authority, path }) {
+  return (
+    /^[\x21-\x7e]+$/u.test(authority)
+    && /^[\x21-\x7e]*$/u.test(path)
+    && !authority.includes('%')
+    && !path.includes('%')
+    && !/^[A-Za-z]:$/u.test(authority)
+    && !/^\/[A-Za-z]:(?:\/|$)/u.test(path)
+  );
+}
+
+function isSafeHttpPath(url) {
+  if (/%25/iu.test(url.pathname)) {
+    return false;
+  }
+
+  let decodedPathname;
+
+  try {
+    decodedPathname = decodeURIComponent(url.pathname);
+  } catch {
+    return false;
+  }
+
+  const pathWithoutLeadingSlash = decodedPathname.startsWith('/')
+    ? decodedPathname.slice(1)
+    : decodedPathname;
+
+  return (
+    !/\p{C}/u.test(decodedPathname)
+    && !decodedPathname.includes('\\')
+    && !/^[A-Za-z]:(?:[\\/]|$)/u.test(pathWithoutLeadingSlash)
+  );
+}
+
+export const idSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .refine((value) => !/(?:\s|\p{C})/u.test(value));
+
+export const cursorSchema = z
+  .string()
+  .min(1)
+  .max(512)
+  .refine((value) => !/(?:\s|\p{C})/u.test(value));
+
+export const revisionSchema = z
+  .string()
+  .regex(/^(?:0|[1-9][0-9]{0,19})$/);
+
+export const timestampSchema = z
+  .string()
+  .min(20)
+  .max(35)
+  .regex(
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/,
+  )
+  .pipe(z.iso.datetime({ offset: true }));
+
+export const sha256Schema = z.string().regex(/^[0-9a-f]{64}$/);
+
+export const sourceUriSchema = z
+  .string()
+  .min(1)
+  .max(MAX_SOURCE_URI_LENGTH)
+  .transform((value, context) => {
+    const rawUri = parseRawHierarchicalUri(value);
+
+    if (
+      rawUri === null
+      || !ALLOWED_SOURCE_URI_SCHEMES.has(rawUri.scheme)
+      || isUnsafeRawSourceUri(value, rawUri)
+      || (
+        CUSTOM_SOURCE_URI_SCHEMES.has(rawUri.scheme)
+        && !isSafeCustomSourceUri(rawUri)
+      )
+      || (
+        HTTP_SOURCE_URI_SCHEMES.has(rawUri.scheme)
+        && /%(?![0-9A-Fa-f]{2})/u.test(value)
+      )
+    ) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Expected an allowed absolute source URI',
+      });
+      return z.NEVER;
+    }
+
+    let uri;
+
+    try {
+      uri = new URL(value);
+    } catch {
+      context.addIssue({
+        code: 'custom',
+        message: 'Expected a valid absolute URI',
+      });
+      return z.NEVER;
+    }
+
+    if (
+      uri.username !== ''
+      || uri.password !== ''
+      || uri.search !== ''
+      || uri.hash !== ''
+      || uri.host === ''
+      || (
+        HTTP_SOURCE_URI_SCHEMES.has(rawUri.scheme)
+        && !isSafeHttpPath(uri)
+      )
+    ) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Expected a non-local URI without credentials, query, or fragment',
+      });
+      return z.NEVER;
+    }
+
+    const canonicalUri = uri.href;
+    const canonicalRawUri = parseRawHierarchicalUri(canonicalUri);
+
+    if (
+      canonicalUri.length > MAX_SOURCE_URI_LENGTH
+      || canonicalRawUri === null
+      || (
+        CUSTOM_SOURCE_URI_SCHEMES.has(rawUri.scheme)
+        && !isSafeCustomSourceUri(canonicalRawUri)
+      )
+    ) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Canonical source URI exceeds the maximum length',
+      });
+      return z.NEVER;
+    }
+
+    try {
+      new URL(canonicalUri);
+    } catch {
+      context.addIssue({
+        code: 'custom',
+        message: 'Canonical source URI must remain parseable',
+      });
+      return z.NEVER;
+    }
+
+    return canonicalUri;
+  });

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

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+
+import { canonicalJson } from '../publication/canonical-json.js';
+import {
+  ProposalStatus,
+  WorkspaceRole,
+  WorkspaceVisibility,
+} from './constants.js';
+import { refineUtf8JsonByteBudget } from './json-budget.js';
+import {
+  cursorSchema,
+  idSchema,
+  revisionSchema,
+  timestampSchema,
+} from './scalar-contract.js';
+import { parseProtocolValue } from './validation.js';
+
+const MAX_SYNC_EVENTS = 500;
+const MAX_SYNC_PAGE_BYTES = 1_048_576;
+
+function createWorkspaceEventSchema(type, data) {
+  return z.strictObject({
+    eventId: idSchema,
+    workspaceRevision: revisionSchema,
+    recordedAt: timestampSchema,
+    type: z.literal(type),
+    data,
+  });
+}
+
+const workspaceUpdatedEventSchema = createWorkspaceEventSchema(
+  'workspace.updated',
+  z.strictObject({
+    visibility: z.enum(Object.values(WorkspaceVisibility)),
+  }),
+);
+
+const membershipChangedEventSchema = createWorkspaceEventSchema(
+  'membership.changed',
+  z.strictObject({
+    subjectId: idSchema,
+    role: z.enum(Object.values(WorkspaceRole)).nullable(),
+  }),
+);
+
+const episodeRecordedEventSchema = createWorkspaceEventSchema(
+  'episode.recorded',
+  z.strictObject({ episodeId: idSchema }),
+);
+
+const factActivatedEventSchema = createWorkspaceEventSchema(
+  'fact.activated',
+  z.strictObject({ factId: idSchema }),
+);
+
+const factSupersededEventSchema = createWorkspaceEventSchema(
+  'fact.superseded',
+  z
+    .strictObject({
+      factId: idSchema,
+      replacedByFactId: idSchema,
+    })
+    .superRefine((data, context) => {
+      if (data.factId === data.replacedByFactId) {
+        context.addIssue({
+          code: 'custom',
+          path: ['replacedByFactId'],
+          message: 'A fact cannot supersede itself',
+        });
+      }
+    }),
+);
+
+const factRetractedEventSchema = createWorkspaceEventSchema(
+  'fact.retracted',
+  z.strictObject({ factId: idSchema }),
+);
+
+const proposalPendingEventSchema = createWorkspaceEventSchema(
+  'proposal.pending',
+  z.strictObject({ proposalId: idSchema }),
+);
+
+const proposalDecidedEventSchema = createWorkspaceEventSchema(
+  'proposal.decided',
+  z.strictObject({
+    proposalId: idSchema,
+    status: z.enum([
+      ProposalStatus.EFFECTIVE,
+      ProposalStatus.REJECTED,
+    ]),
+  }),
+);
+
+const signingKeyRevokedEventSchema = createWorkspaceEventSchema(
+  'signing_key.revoked',
+  z.strictObject({ keyId: idSchema }),
+);
+
+export const workspaceEventSchema = z.discriminatedUnion('type', [
+  workspaceUpdatedEventSchema,
+  membershipChangedEventSchema,
+  episodeRecordedEventSchema,
+  factActivatedEventSchema,
+  factSupersededEventSchema,
+  factRetractedEventSchema,
+  proposalPendingEventSchema,
+  proposalDecidedEventSchema,
+  signingKeyRevokedEventSchema,
+]);
+
+export const syncPageSchema = z
+  .strictObject({
+    workspaceId: idSchema,
+    events: z.array(workspaceEventSchema).max(MAX_SYNC_EVENTS),
+    nextCursor: cursorSchema.nullable(),
+    hasMore: z.boolean(),
+  })
+  .superRefine((page, context) => {
+    const fingerprintsByEventId = new Map();
+    let previousUniqueRevision;
+
+    page.events.forEach((workspaceEvent, index) => {
+      const fingerprint = canonicalJson(workspaceEvent);
+      const previousFingerprint = fingerprintsByEventId.get(
+        workspaceEvent.eventId,
+      );
+
+      if (previousFingerprint !== undefined) {
+        if (previousFingerprint !== fingerprint) {
+          context.addIssue({
+            code: 'custom',
+            path: ['events', index, 'eventId'],
+            message: 'An event ID cannot identify conflicting events',
+          });
+        }
+
+        return;
+      }
+
+      fingerprintsByEventId.set(workspaceEvent.eventId, fingerprint);
+      const currentRevision = BigInt(workspaceEvent.workspaceRevision);
+
+      if (
+        previousUniqueRevision !== undefined
+        && currentRevision < previousUniqueRevision
+      ) {
+        context.addIssue({
+          code: 'custom',
+          path: ['events', index, 'workspaceRevision'],
+          message: 'Workspace revisions must be nondecreasing',
+        });
+      }
+
+      previousUniqueRevision = currentRevision;
+    });
+
+    if (page.hasMore && page.events.length === 0) {
+      context.addIssue({
+        code: 'custom',
+        path: ['events'],
+        message: 'A continued Sync page requires at least one event',
+      });
+    }
+
+    if (page.hasMore && page.nextCursor === null) {
+      context.addIssue({
+        code: 'custom',
+        path: ['nextCursor'],
+        message: 'A continued Sync page requires a next cursor',
+      });
+    }
+
+    refineUtf8JsonByteBudget(
+      page,
+      context,
+      MAX_SYNC_PAGE_BYTES,
+      'Sync page',
+    );
+  });
+
+export function parseSyncPage(value) {
+  return parseProtocolValue(syncPageSchema, value, 'Sync page');
+}

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

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+const unsafeWireTextPattern = /\p{C}/u;
+
+function hasSafeWireText(value) {
+  return !unsafeWireTextPattern.test(value);
+}
+
+export function createPreservedSemanticTextSchema(maxLength) {
+  return z
+    .string()
+    .min(1)
+    .max(maxLength)
+    .refine((value) => (
+      value === value.trim()
+      && hasSafeWireText(value)
+    ));
+}
+
+export function createPreservedContentTextSchema(maxLength) {
+  return z
+    .string()
+    .min(0)
+    .max(maxLength)
+    .refine((value) => (
+      (value.length === 0 || value === value.trim())
+      && hasSafeWireText(value)
+    ));
+}
+
+export function createNormalizedSemanticTextSchema(maxLength) {
+  return z
+    .string()
+    .min(1)
+    .max(maxLength)
+    .refine(hasSafeWireText)
+    .transform((value) => value.trim())
+    .pipe(z.string().min(1).max(maxLength));
+}

package/src/workspace-protocol/validation.js

@@ -0,0 +1,66 @@
+const MAX_ISSUES = 20;
+const MAX_ISSUE_CODE_LENGTH = 64;
+const MAX_ISSUE_MESSAGE_LENGTH = 256;
+const MAX_PATH_SEGMENTS = 16;
+const MAX_PATH_SEGMENT_LENGTH = 128;
+const ISSUE_MESSAGES = Object.freeze({
+  unrecognized_keys: 'Unexpected field',
+  invalid_type: 'Invalid value type',
+  too_small: 'Value is below the allowed minimum',
+  too_big: 'Value exceeds the allowed maximum',
+  invalid_format: 'Value has an invalid format',
+  invalid_value: 'Value is not allowed',
+  invalid_union: 'Value does not match any allowed shape',
+  custom: 'Value violates a protocol constraint',
+});
+const DEFAULT_ISSUE_MESSAGE = 'Value failed protocol validation';
+
+function truncateSafely(value, maxLength) {
+  try {
+    return String(value).slice(0, maxLength);
+  } catch {
+    return '[unprintable]';
+  }
+}
+
+function projectPath(path) {
+  const projectedPath = path.slice(0, MAX_PATH_SEGMENTS).map((segment) => {
+    if (typeof segment === 'number') {
+      return segment;
+    }
+
+    return truncateSafely(segment, MAX_PATH_SEGMENT_LENGTH);
+  });
+
+  return Object.freeze(projectedPath);
+}
+
+function projectIssue({ code, path }) {
+  const message = Object.hasOwn(ISSUE_MESSAGES, code)
+    ? ISSUE_MESSAGES[code]
+    : DEFAULT_ISSUE_MESSAGE;
+
+  return Object.freeze({
+    code: truncateSafely(code, MAX_ISSUE_CODE_LENGTH),
+    path: projectPath(path),
+    message: truncateSafely(message, MAX_ISSUE_MESSAGE_LENGTH),
+  });
+}
+
+export class ProtocolValidationError extends TypeError {
+  constructor(label, issues) {
+    super(`${label} failed protocol validation`);
+    this.name = 'ProtocolValidationError';
+    this.issues = Object.freeze(issues.slice(0, MAX_ISSUES).map(projectIssue));
+  }
+}
+
+export function parseProtocolValue(schema, value, label) {
+  const result = schema.safeParse(value);
+
+  if (!result.success) {
+    throw new ProtocolValidationError(label, result.error.issues);
+  }
+
+  return result.data;
+}