Skip to content

Floor OS — Pilot Data Handling and Platform Limitations

Author: Werner Santos Date: 2026-05-19 Version: 1.0 (draft for review)

1. Purpose

This document is the data-handling and scope agreement for the Floor OS friendly pilot. It tells a pilot agency exactly what data they may upload, what they should not, what the platform does today, and what it does not do yet. This is not a Master Services Agreement (MSA); it sits alongside one. The MSA governs liability, IP, and payment — this document governs operational scope and data expectations. Where the two conflict, the MSA controls.

Floor OS (internally: Licensing_Intelligence_Studio) is a pre-execution compliance gating product for collections operations. It sits between intent and action: an agency's dialer, CRM, or payment processor asks Floor OS before making a contact attempt, running a payment, or sending a letter, and Floor OS returns an allow or block with a reason and a tamper-evident audit receipt.

2. What Floor OS Does in a Pilot

  • Runs a 12-gate pre-execution compliance pipeline per account action. Gates cover account validity (G1), portfolio strategy rules (G2), legal compliance including TCPA consent, Reg F 7-in-7, time-of-day, DNC, and state-law checks (G3), escalation logic (G4-G5), fairness and anti-harassment detection (G6), timing and contact-frequency controls (G7), channel appropriateness and DNC (G9), and infrastructure health checks (G12). Each gate returns pass or block with a reason and a statutory reference where applicable.
  • Produces SHA-256 HMAC-chained tamper-evident audit receipts per gate evaluation. Every allowed or blocked action is recorded in the compliance_event_log table, keyed by a time-boxed audit_id, before any downstream action occurs.
  • Isolates each tenant's data behind JWT tenant-scoped access. One agency's accounts, gate results, and audit log are not visible to any other tenant. The tenant_id is extracted from the signed JWT only — it cannot be supplied or overridden by a request body.
  • Exposes a CSV import path for uploading pilot accounts, a gate API (POST /api/v1/compliance/contact-check) for live gate evaluation, and a role-based UI with four roles: admin, manager, IT, and agent. Each role sees a scoped surface appropriate to its function.

3. What Data the Customer May Upload

The following fields are explicitly approved for pilot upload without additional written authorization:

  • account_id — your internal account identifier, used as the primary key in Floor OS
  • state — two-letter state code (used for state-law gating, SOL checks, time-of-day rules)
  • balance_bucket or balance_amount — either a bucketed range (e.g., "$0-500") or a numeric amount; used for gate scoring and payment authorization logic
  • status — account status (e.g., active, bankruptcy, closed, sold, deceased); used by G1 VALIDATION gate
  • consent_tcpa — boolean or timestamp; TCPA written consent to contact via phone
  • consent_written — boolean or timestamp; general written consent flag
  • consent_call — boolean; explicit consent to autodialed or prerecorded calls
  • dnc_flag — boolean; internal DNC designation; supplements the G9 channel gate check
  • time_zone — IANA time zone string (e.g., America/Los_Angeles); used for time-of-day compliance checks
  • last_contact_date — ISO 8601 date; used by G7 TIMING gate and Reg F 7-in-7 check
  • vehicle_vin, vehicle_plate — VIN or plate number if the account relates to a vehicle repossession use case; approved for upload if relevant to your portfolio
  • assigned_agent_id — your internal agent identifier; used for G2 STRATEGY and G6 FAIRNESS gate checks

If you need to upload a field not on this list, contact Werner before uploading. Do not assume unlisted fields are safe to include.

4. What Data the Customer Should Not Upload (Unless Separately Approved in Writing)

The fields below carry disproportionate risk relative to their pilot value. Do not include them in a pilot CSV or API call without a separate written approval from Werner:

  • Full Social Security Number. Last 4 digits may be acceptable if required for account identity verification — but only with separate written approval specifying the use case.
  • Date of Birth. Not required by any Floor OS gate. Omit.
  • Full street address. State and ZIP code are sufficient for most gating logic. A full address is not required for the pilot.
  • Bank account or routing numbers. Floor OS gates payment authorization; it does not store or transmit raw payment credentials. Use an account status flag instead.
  • Credit or debit card data. Same as above. Never upload card numbers.
  • Medical information of any kind. Floor OS does not hold a Business Associate Agreement (BAA). If your portfolio includes medical debt, discuss this with Werner before the pilot starts. Floor OS is not HIPAA-scoped in Phase 1.
  • Raw call recordings. Not accepted by any Floor OS API endpoint.
  • Free-form notes fields containing any of the above. If your CRM exports a notes column, scrub it before upload. Floor OS does not parse notes for compliance — any PII in that column is stored without benefit.

5. Minimum-Data Principle

Upload the minimum data needed to exercise the compliance gate you are testing, not a full production export. If a field is not referenced by a gate, a rule, or a workflow in the pilot scope, do not include it. This is not a bureaucratic requirement — it is risk management. A narrower data set means a smaller blast radius if something goes wrong, faster investigation, and a cleaner deletion at pilot end. Review Section 3 before each upload and ask: does this column drive a gate decision or a UI display? If the answer is neither, leave it out.

Target 500 to 2,000 accounts for the pilot. This range is intentional: large enough to surface real edge cases (accounts in bankruptcy, accounts on state DNC lists, accounts that trip Reg F 7-in-7), small enough that Werner can investigate every gate evaluation manually if something unexpected appears in the audit log. A pilot with 50 accounts will not reveal statistically meaningful gate-block rates. A pilot with 50,000 accounts will make investigation of anomalies slow. Stay in the 500-2,000 range unless the Order Form specifies otherwise.

7. Pilot Duration

Typical pilot duration is 30 to 60 days from first account upload to retrospective sign-off. All timelines — start date, end date, and any extensions — are agreed in writing in the Order Form or Statement of Work. This document sets expectations only; it does not override the dates in your Order Form.

8. Retention and Deletion

  • Data uploaded during the pilot is stored on Floor OS's Google Cloud infrastructure in us-central1. The current backing store is SQLite on Cloud Run ephemeral container storage. A migration to managed PostgreSQL (Cloud SQL) or another durable backend is planned for the production phase; it is not in place during the pilot. Practical implication: data written during a Cloud Run instance's lifetime is preserved while that instance is running, but Cloud Run cold starts, scale-to-zero recovery, and redeploys replace the container and reset the local SQLite file. Long-term retention and export policy is therefore agreed during pilot onboarding (see "Audit hash chain — Phase 1 persistence scope" in §9 and the export option in this section).
  • At pilot end, the customer may request a full data export: a CSV of all accounts and a CSV of all audit receipts in their tenant's scope. Werner will provide the export within 5 business days of the request.
  • On written request, Werner will delete all of the customer's tenant data within 30 days of pilot end and provide a written deletion attestation confirming the deletion completed.
  • During the pilot, the customer may request deletion of specific accounts by account_id by contacting Werner directly. Deletion requests are processed within 2 business days.
  • Floor OS does not replicate tenant data to third-party analytics services. Sentry error tracking receives application errors with send_default_pii=False — see Section 9 for details.

9. Known Platform Limitations

These are honest. Do not assume a limitation not listed here has been resolved — if in doubt, ask.

  • SQLite single-instance backend. Floor OS runs on a single Cloud Run instance backed by SQLite. Horizontal scaling is not enabled. Concurrent write contention is possible under heavy load. This is a Phase 2 item (managed PostgreSQL + multi-instance). For a 500-2,000 account pilot with normal gate call rates, this is not expected to be a problem in practice.
  • Stripe billing in demo mode. The pilot is free of charge. Stripe is integrated but not processing live payments. No billing occurs during the pilot period.
  • No SSO or SAML. Pilot admins log in with email and password. SSO/SAML is a Phase 2 feature. If your agency requires SSO as a condition of data upload, this pilot is not the right fit yet.
  • No native mobile app. Floor OS is a browser-based product. There is no iOS or Android app.
  • Audit receipts are HMAC-SHA-256 chained. This is strong tamper-evidence but is not the same as a cryptographic signature by an independent third party. Ed25519 signing against an external notary is on the Phase 2/3 roadmap (tracked in issue #33). During the pilot, the hash chain proves internal integrity; it does not constitute a third-party attestation.
  • Audit hash chain — Phase 1 persistence scope. Phase 1 hash-chain proof is runtime-instance scoped while SQLite is used on Cloud Run ephemeral storage. The chain verifies tamper-evidence for entries written by the currently running Cloud Run container instance; it is rebuilt fresh when Cloud Run cold-starts or redeploys (the local SQLite file is recreated). Cross-deploy durable audit retention is not claimed in Phase 1. Durable audit retention is a Phase 2 item via Cloud SQL/Postgres or another durable backend. Buyer-safe claim: Floor OS can generate audit proof for governed events during pilot workflows, but long-term retention/export policy must be agreed during pilot onboarding (see §8 export option). Provider enforcement proofs (e.g., the Twilio BLOCK no-send / ALLOW one-message contract from Loop 1.10) remain valid regardless of audit-chain rebuild scope — those proofs are generated and reviewed within the active runtime session and recorded externally via the provider's own logs (e.g., Twilio Messages API).
  • CSV intake PII scrub (Loop 1.16b — code-enforced as of 2026-05-22). The §4 forbidden-fields policy is now enforced in code, not just by upload guidance:
  • _scrub_pii_fields in collections_pkg/routes/competitor_import.py drops top-level phone, phone_number, home_phone, cell_phone, mobile, address, street_address, mailing_address, debtor_name, name, full_name, first_name, last_name, ssn, ssn_last4, ssn_last_4, last4, email, date_of_birth, dob, employer, bank_account, bank_routing, card_number, card_pan before ingest_accounts is called. If a customer's CSV includes any of these columns, the values do not land on accounts.
  • accounts.raw_data (a TEXT column that used to receive json.dumps(<original CSV row>)) now stores only an allowlisted operational-metadata blob: account_id, balance, age_days, contact_count, payment_total, status, disposition, state, department, portfolio, placement_date, follow_up_date, date_last_paid, arrangement_amount, compliance_risk. The original CSV row is not retained.
  • A _truncate_ssn_to_last4(value) helper exists for the deliberate, written-approval-only path where a tenant has agreed last-4 may be persisted. By default the scrub set drops ssn and ssn_last4 entirely and this helper is not wired into the import path.
  • This does NOT mean Floor OS now accepts unrestricted customer files. The §4 guidance for what customers should NOT upload still applies — the scrub is a second line of defence, not an invitation to ignore the first one.
  • Sentry error tracking with limited PII debugging. Unhandled application errors are sent to Sentry with send_default_pii=False. This means production debugging is constrained if a bug is customer-data-specific — Werner cannot see the account_id or field values in an error trace. This is intentional (privacy over debuggability) but means some bugs may require Werner to add targeted temporary logging to reproduce.
  • Uptime monitoring active but no contractual SLA. The /api/health endpoint is polled every 60 seconds and the frontend every 5 minutes via Google Cloud Monitoring uptime checks. There is no written availability SLA in the pilot. Werner reviews monitoring alerts and will notify pilot customers of outages.
  • State-by-state regulatory adaptation is incomplete. This is the most important known limitation for a collections customer. The 12-gate pipeline enforces federal frameworks (FDCPA, TCPA, Reg F, FCRA, ECOA, SCRA, bankruptcy stay). State-specific overlays — state mini-FDCPA statutes, state-specific time-of-day rules beyond the federal 8am-9pm window, state DNC lists, state SOL periods — are partially implemented and vary by state. Do not rely on Floor OS as a complete state-law compliance solution during the pilot. Use it to validate federal-framework gating and to test the audit trail workflow. Confirm your own state-law posture with counsel.
  • CAN-SPAM email channel not fully gated. Email is a recognized channel in the gate schema, but CAN-SPAM-specific checks (opt-out propagation, physical address in footer, sender identity) are not enforced by the gate in Phase 1. If email outreach is part of your pilot scope, note this gap.
  • No real-time DNC list integration. The G9 channel gate checks the dnc_flag field you upload with the account. It does not query a live national or state DNC registry in real time. Your responsibility to keep the uploaded DNC flag current.
  • No SOC 2 certification. Floor OS is not SOC 2 certified. Type I scoping has not started. If SOC 2 is a procurement requirement, this pilot is not the right fit yet.
  • No HIPAA / BAA. See Section 4. Medical debt portfolios require a Business Associate Agreement that does not exist for Floor OS in Phase 1.

10. Support During the Pilot

  • Primary contact: Werner Santos — werner@wernerharmoniclabs.com
  • Response window: 1 business day for non-urgent questions (configuration, how-to, data questions). Same-day best-effort for production breakage (gate API returning errors, upload failures, UI inaccessible) during the pilot.
  • Outage notification: Google Cloud Monitoring uptime alerts are registered to Werner's account. Werner will notify pilot customers via email when an outage is confirmed and when service is restored.
  • Error tracking: Sentry receives any unhandled application errors automatically. Werner reviews Sentry daily during active pilot periods.
  • No 24/7 on-call. This is a friendly pilot, not a production SLA. Werner operates on Pacific Time (US). For anything that cannot wait, lead with "urgent" in the subject line.

11. What Success Looks Like for the Pilot

The following outcomes define a successful pilot. Specific numbers for N and X are agreed in the Order Form.

  • At least N gate evaluations completed with audit receipts retained and retrievable (N agreed in Order Form — recommended minimum: 500 gate calls to cover the uploaded portfolio at least once).
  • At least one full end-to-end cycle completed: CSV import → intake scan → gate evaluation → audit receipt → CSV export of results.
  • Zero cross-tenant data leak incidents: no account, receipt, or audit event from Tenant A visible to Tenant B at any point during the pilot.
  • No PII exfiltration to Sentry or any third-party service confirmed by Werner's review of Sentry during the pilot period.
  • Pilot admin can run daily operations — reviewing gate blocks, checking the audit log, importing new accounts — without contacting Werner more than X times per week for operational support (X agreed in Order Form; suggested default: 2).
  • Customer signs a written pilot retrospective confirming: what worked, what didn't, and whether Floor OS addresses the compliance gating problem for their operation.

12. Out of Scope for the Pilot

The following are explicitly outside what the pilot covers:

  • Marketing the pilot externally without Werner's written approval. Do not announce, blog, or reference Floor OS in any public communication during the pilot without a co-marketing agreement.
  • Reverse-engineering or cloning the Floor OS code, database schema, gate logic, or audit receipt format. The software is proprietary IP of Werner Harmonic Labs LLC.
  • Uploading data not owned by the customer or not lawfully obtainable for collections work. You represent that all accounts you upload are accounts your agency has legal authority to collect on.
  • Connecting Floor OS to live consumer-facing communication channels — SMS, outbound voice, email — without separate written approval. The pilot is for gate validation and audit trail verification, not for conducting live consumer contact campaigns. Inbound webhook adapters (Five9, Twilio, Convoso, generic) may be configured for testing purposes; outbound consumer-facing sends require explicit written approval.
  • Using the pilot as a substitute for legal counsel on state-specific compliance questions. Floor OS provides a gating layer and an audit trail; it is not a law firm and its gate decisions are not legal advice.

13. Document Status and Version

Field Value
Author Werner Santos
Organization Werner Harmonic Labs LLC
Date 2026-05-19
Version 1.0 (draft for review)
Status Pre-pilot — for review by pilot agency and Werner before first account upload

This document supersedes any informal data-handling guidance sent via email or Slack prior to this date. If there is a conflict between this document and the Order Form / SOW, the Order Form controls on commercial terms; this document controls on operational data-handling expectations.

See also: - docs/PILOT_SCOPE.md — canonical in-scope / deferred features for pilot v1 - docs/PR_DISCIPLINE.md — engineering change control (internal) - docs/RALPH_LOOP.md — engineering loop discipline (internal) - docs/engineering/ENVIRONMENT_VARIABLES.md — deployment configuration reference (internal)